Skip to main content
When a run fails or behaves unexpectedly, start here. The most common issues and their fixes are listed below.
Symptom: Run status is FAILED and the gate results show 3 failed loops for a single gate.Cause: The agent attempted to self-repair 3 times (the default limit) and could not produce code that passes the gate.Fix:
  • Run zombiectl run status <id> and inspect the stderr from the final loop attempt.
  • Check whether the failing Make target (make lint, make test, or make build) works locally on a clean checkout.
  • Simplify the spec — smaller, more focused specs produce higher pass rates.
  • If your repo’s Make targets have environment-specific dependencies, ensure they work in a clean Linux container.
Symptom: Run fails immediately with a validation error before any gates execute.Cause: The spec references files or paths that do not exist in the target repository, or the spec content is empty/malformed.Fix:
  • Validate the spec locally before submitting:
zombiectl spec validate <file>
  • Ensure all file paths referenced in the spec exist on the base branch HEAD.
  • Check that the spec is valid markdown with at least a title and one requirement.
Symptom: Run status is FAILED with a timeout error. No gate exhaustion — the run simply ran out of time.Cause: The run exceeded its wall time limit. This can happen with large specs, slow test suites, or complex build steps.Fix:
  • Reduce the scope of the spec. Break large features into multiple smaller specs.
  • Check whether your make test or make build targets are unusually slow.
  • If you need more time, increase the budget in your agent profile settings.
Symptom: Run fails with an out-of-memory error. The worker process was killed.Cause: The agent exceeded the memory limit (512 MB default). This typically happens with large file operations, massive dependency installs, or memory-intensive build steps.Fix:
  • Avoid specs that require processing very large files.
  • Check whether your build step has a known memory spike (e.g., TypeScript compilation of a very large project).
  • Contact support if you consistently hit OOM on normal-sized repos.
Symptom: Run submission is rejected with a billing error. No run is created.Cause: Your free plan $10 credit has been used up.Fix:
  • Check your current balance in the dashboard.
  • Upgrade to the Scale plan for higher limits and per-run billing.
Symptom: Run submission is rejected with a duplicate error.Cause: The same spec content, repository, and base commit SHA already has an active run (status QUEUED or RUNNING).Fix:
  • Wait for the existing run to complete or fail.
  • If you want to re-run the same spec, push a new commit to the base branch so the base commit SHA changes.
  • Alternatively, modify the spec content (even a whitespace change) to make it unique.

​
Run replay

zombiectl runs replay is planned for a future release. Use the API endpoint below in the meantime.
Replay the complete event history of a finished run via the API: 
curl https://api.usezombie.com/v1/runs/run_01JQ7K...:replay \
  -H "Authorization: Bearer $ZOMBIE_TOKEN"