Why Is My Coding Agent Stuck in a Loop?

Quick answer
Most loops are a missing or misleading verification signal, not a reasoning failure.
If the test output is ambiguous, stale, or cached, the agent cannot tell success from failure and tries again.
Repeated attempts at the same error usually mean the error message does not identify the real cause, or the agent is editing a file the runtime does not use.
Break the loop by stopping the run, reading the last failing output yourself, and giving the agent the fact it is missing.
Prevent it with a stop condition and a rule that forbids the third identical attempt.

Why does an agent retry the same fix?

Because it receives the same failure. A cached test run, a watcher that did not reload, a build that writes to a different directory, or a suite that fails on an unrelated test all produce output that looks like the problem is unchanged. The agent concludes its fix did not work and tries a variation.

The second cause is a wrong mental model of the code. The agent edits a handler that is not mounted, a config that is overridden, or a duplicate file the build ignores. Each edit is reasonable; none affects the observed behaviour.

How do you diagnose it quickly?

Stop the run and look at the last failing command yourself. Confirm that it exercises the code the agent changed, that the process restarted, and that the failure is the one the agent thinks it is. That check takes a minute and usually explains the loop.

Then look at what changed. If nothing changed in the runtime path, the agent is editing the wrong place. If the failure output is identical byte for byte across attempts, suspect caching or a stale process rather than the code.

How do you get it unstuck?

Give it the fact it lacks: the entry point, the command that actually runs the path, the log line that shows which handler executed. A precise fact ends the search more reliably than an instruction to think harder.

If the task is ambiguous, narrow it. “Make the tests pass” invites a loop when several tests fail for different reasons. “Make test/auth.test.ts pass; ignore the other failures” gives it a finish line.

How do you prevent loops?

Define what success looks like as a command and its expected output, and state a stop rule: after two failed attempts at the same error, stop and report. The rule converts an unbounded loop into a report you can act on.

Also fix the feedback loop itself. Make the test command print the failing assertion, disable caching for the inner loop, and confirm the dev server reloads. An agent with a trustworthy signal converges; one with a noisy signal spins.

Where this bites vibecoders
The loop usually looks productive: the agent keeps writing plausible patches and the messages stay confident. Nothing in them tells you the test command was failing on a different test the whole time. Interrupt early and read the raw output.

Where AI coding assistants get this wrong

Letting the agent retry the same approach more than twice.
Trusting a cached or stale test result.
Editing a file the runtime does not load.
Giving a broad goal with several failing checks.
Suppressing the error to make the loop end.
Assuming the agent knows which handler executed.

Checklist

Stop the run and read the last failure yourself.
Confirm the command exercises the changed code.
Check for caching and stale processes.
Give the agent the entry point and the log line.
Narrow the goal to one failing check.
Add a stop rule after two identical attempts.

FAQ

Can a loop be a model problem?

Sometimes, particularly if the task exceeds what the model can hold. But before blaming the model, confirm the feedback signal is accurate and the agent is editing the code that runs. Most loops disappear when the signal is fixed.

Should I increase the token budget to let it finish?

No. A loop consumes budget without converging, so more budget buys more attempts. Fix the signal or narrow the task instead. Budget is a limit, not a diagnosis.

What if it loops on a flaky test?

Treat the flake as the task. Quarantine the test, run it in isolation, and fix the nondeterminism. An agent asked to make a flaky test pass will produce changes that pass sometimes, which is worse than a clear failure.

How do I report it back to the team?

Note the command, the output, and the file the agent was editing. That tuple usually reveals whether the loop was signal, environment, or task definition. It also becomes a rule in AGENTS.md so the next run starts better.