Skip to content
Documentation
Getting started
Configuration
Capabilities
Control
Reference

Troubleshooting

Common failures and what they mean.

Start with two commands. forge config shows what actually resolved, and -v shows every step the agent took. Most problems are visible in one of them.

$ forge config$ forge -v "the task that went wrong"

forge: command not found

The install worked; the binary is not on your PATH. It lives in uv's tool directory.

$ uv tool update-shell$ exec $SHELL -l$ forge --version

If it is still missing, uv tool list will tell you whether Forge is installed at all. See Installation.

Exits immediately with code 2

Code 2 means misconfiguration - Forge never started the loop, so retrying will fail identically until you change something. Three causes account for almost all of it.

No model configured

There is no default model. Set ANTHROPIC_MODEL, or pass --model.

$ export ANTHROPIC_MODEL="claude-sonnet-4-5"

Sandbox unavailable

--sandbox docker with no reachable daemon. Confirm with docker info, start Docker, or drop the flag.

Bad flag or value

An unknown flag, or an invalid value for --mode or --sandbox. The error names the offending argument; CLI reference has the accepted values.

Authentication errors

  • 401 or 403 - the credential is missing, expired, or not valid for this endpoint. forge config shows whether a key was found at all, redacted.
  • 404 on the model - usually a model id your credential cannot reach, or a gateway that expects different names.
  • Connection refused - a stale ANTHROPIC_BASE_URL in your shell profile pointing at a proxy that is no longer running. Unset it to go direct.
  • 429 - rate limited by the provider. Not something Forge can retry its way out of on a small quota.

Stops at max iterations

Exit code 1 with the ceiling reached means the agent was still working when it ran out of budget. Raising the limit is occasionally right and usually not - a task that needs 60 iterations is normally a task that was described too loosely.

  • Split it. Two tasks with clear finish lines beat one that requires the agent to infer the shape of the work.
  • Say how to verify it. “Make pytest tests/test_auth.py pass” converges; “improve the auth code” does not.
  • Read the log for a loop - the same edit reverted repeatedly means a test the agent cannot satisfy, and it will not get there with more attempts.
  • Try a stronger model. Iteration count is usually a reasoning problem, not a budget problem.

A command was refused

If the log shows a refusal that no approval prompt preceded, the command matched the deny list. That is not mode-dependent and there is no override - git push and sudo are the two people hit most often.

A prompt you did not expect, on the other hand, is escalation working: a shell command matched a dangerous pattern and was promoted to destructive. Both lists are on the Permissions page.

Declining a call is safe. The refusal returns to the model as a result, and it will usually propose a different route to the same outcome.

Everything fails in the sandbox

  • Command not found - the tool is on your machine, not in the image. Set an image with your toolchain.
  • Network unreachable - containers start with networking off. Dependency installs and tests that call live services both fail.
  • Killed mid-build - the memory cap. Raise it, or build somewhere else.

Sandbox covers the defaults and how to change them.

It says it is done, and it is not

The most important failure to recognise, because it is the one that looks like success. Almost always a model that edited files without running anything.

  • Check the log for a shell call. No test run means no verification, whatever the summary says.
  • Name the command in the task. “…and make sure npm test passes” changes behaviour more than any flag.
  • Move to a stronger model. Stopping early is characteristic of smaller ones.
  • Read the diff. git diff after a run takes seconds and is the only real check.

Long sessions lose the thread

Context is compacted when it fills, so early detail is summarised. Use /clear when you switch to an unrelated task - a fresh context is cheaper and the agent stops carrying assumptions from work that no longer applies.

Reporting a bug

Include the output of forge --version and forge config, the task you gave, and the -v log. Redact what you must; the log is the part that makes a report actionable.

  • Open an issue - bugs, and behaviour that surprised you.
  • FAQ - including what is knowingly unfinished.