AI agent crash loops: how to stop restarts before they drain a run
An AI agent crash loop is a restart policy doing exactly what it was told, after the original failure has stopped being recoverable. A Gateway fails to start, the supervisor launches it again, and the same bad configuration, unavailable dependency, or expired credential kills it once more. The machine stays busy; the task never resumes.
The practical fix is to treat restart behavior as a bounded recovery workflow, not a promise that every failure deserves another try. Set a retry ceiling, preserve the evidence needed to diagnose the failure, and move the service into a visible repair state when the ceiling is reached. OpenClaw v2026.7.1 adopts that last part for repeatedly failing Gateways: instead of restarting forever, the system leaves a stable repair path.
What makes an AI agent crash loop different from a normal retry
A normal retry assumes the next attempt may see a different world. A provider’s temporary 503 may clear. A network route may come back. A process can complete after a short backoff.
A crash loop repeats when the cause is stable. Common examples include:
- a required environment variable or credential is missing;
- an update changes a plugin, tool schema, or configuration value that the runtime can no longer load;
- a local dependency is unavailable at startup;
- the process starts, consumes its initialization work, then exits before it can accept useful work.
The restart manager cannot distinguish those cases merely by restarting. In fact, quick retries can erase the useful part of the incident: logs roll over, dashboards show a service that appears “active,” and an operator sees only the latest failure. Kubernetes documents the same operational failure mode as CrashLoopBackOff: repeated container failures are slowed with backoff because a restart is not a repair.
| Failure pattern | What a retry can do | What an operator needs |
|---|---|---|
| Transient provider or network error | Retry after a bounded delay | A time limit and a fallback path |
| Invalid configuration or missing secret | Reproduce the same error | A paused service and the original error |
| Broken update or incompatible plugin | Restart into the same bad state | Version, dependency, and startup diagnostics |
| Repeated runtime exception | Burn CPU and hide the root cause | A repair state with a clear escalation point |
The distinction matters for autonomous work. A chat assistant that crashes once is inconvenient. A scheduled agent that reboots through its run window can miss the work entirely while still looking “managed” to the person who installed it.
Build a restart policy that can give up
A safe restart policy has four parts. The details vary by process manager, but the control logic does not.
- Use backoff, not immediate relaunches. A delay between attempts prevents one faulty process from monopolizing a machine. Exponential backoff increases the delay after each consecutive failure, then resets only after the service has remained healthy long enough to prove it really recovered.
- Set a maximum attempt count or time budget. The policy needs a stop condition. Without one, “automatic recovery” becomes a loop with no owner.
- Keep the failure context. Save the exit reason, recent logs, version, configuration fingerprint, and the action that triggered the restart. A repair screen that says only “failed” forces the operator to reconstruct the incident from scratch.
- Choose an explicit terminal state. After the budget is exhausted, stop restarting and mark the service as requiring repair. Alert the owner, keep the last good evidence, and avoid accepting new work that cannot complete.
Google’s SRE guidance on overload makes the same point in a broader form: retries spend resources, so they need limits. For agents, the relevant resource is not only CPU or requests. It is also the task’s deadline, the model budget, the session context, and the attention of the person who will eventually debug it.
A small failure budget beats a permanent restart switch
There is no universal number of attempts. A service that manages a long-running local agent needs different thresholds from a stateless web worker. The policy should reflect the recovery evidence available to the next attempt.
| Setting | Reasonable starting point | Why it helps |
|---|---|---|
| Initial delay | A few seconds | Avoids a tight restart loop after a sudden exit |
| Backoff cap | A few minutes | Gives a transient dependency time to recover without parking forever |
| Consecutive-failure ceiling | Small and explicit | Stops a stable configuration error from becoming endless churn |
| Health-reset window | Long enough to complete real work | Prevents one short startup from resetting the failure count |
| Terminal action | Repair state plus notification | Makes human ownership visible before work silently disappears |
The exact values should come from your task window. If a morning briefing must arrive before 09:15, a ten-minute restart budget is not a recovery plan. It is a late failure. If the agent’s work is expensive, a low ceiling is usually safer because each restart may repeat model calls, tool initialization, or browser setup.
OpenClaw v2026.7.1 makes the repair path explicit
OpenClaw’s v2026.7.1 release notes describe a concrete version of this pattern: repeatedly failing Gateways stop restarting forever and leave a stable repair path. That is a better default than a process that endlessly respawns because it keeps both sides of the incident honest:
- the runtime stops spending resources on a failure it cannot fix;
- the operator gets a durable state to inspect rather than a moving target;
- scheduled and channel work can be treated as unavailable instead of appearing to be in progress;
- a deliberate repair can happen before the service is restarted again.
A Gateway may own channels, active sessions, downloads, browser actions, and scheduled tasks. Restarting it repeatedly without a terminal state risks turning one startup error into an unclear chain of missed or duplicated work.
For the underlying architecture, see how OpenClaw works and the self-hosted AI assistant overview. The operational lesson is simple: autonomy needs an owner at the point where automatic recovery stops being credible.
Preserve state before restarting
A crash loop becomes harder to diagnose when every restart destroys the evidence. Preserve enough context to answer four questions:
- What was the process doing? Record the task or session identifier, scheduled job, channel event, and current phase.
- What changed? Capture the deployed version, enabled plugins, model/provider configuration, and a redacted configuration hash.
- Why did it exit? Keep the exception, exit code, and a bounded startup log. Do not dump secrets or complete prompts into a notification.
- What work might need reconciliation? Note tasks that were claimed, messages that may have been delivered, downloads in flight, and tools that may have made a side effect.
That fourth question prevents the other bad outcome: a healthy restart that repeats a side effect. If an agent sent an approval request just before its process died, retrying the entire job without a checkpoint can send it again. Durable task and session state are not merely a convenience for resuming work; they are the boundary that keeps recovery from becoming duplication.
OpenClaw’s interrupted tool-call recovery guide is useful here because it separates a failed action from an unknown action. When the system cannot tell whether a tool completed, it should surface that uncertainty rather than confidently replay it.
Test the failure path before production finds it
Test one disposable bad-configuration case before relying on a restart policy. Verify that backoff increases, the ceiling stops further launches, diagnostic context survives without secrets, and a real health check is required before the failure counter clears. If the service cannot repair itself, the owner should know what to do next; “it restarts” is not an operational answer.
FAQ
What is an AI agent crash loop?
An AI agent crash loop occurs when an agent runtime or Gateway repeatedly exits and its supervisor keeps restarting it even though the underlying problem remains. It wastes resources, hides the original error, and can cause scheduled or channel work to disappear.
Should AI agents restart automatically after a crash?
Yes for a bounded number of attempts when the failure may be transient. The policy should use backoff, preserve diagnostic context, and stop in a visible repair state when retries no longer add new evidence.
What causes repeated agent restarts?
Frequent causes include invalid configuration, missing credentials, incompatible plugins or updates, unavailable local dependencies, and startup exceptions. These need correction, not more attempts.
How does OpenClaw handle repeated Gateway crashes?
OpenClaw v2026.7.1 states that repeatedly failing Gateways stop restarting forever and leave a stable repair path. That gives operators a fixed state to inspect before restarting again.
AI agent crash loops need a terminal repair state
An AI agent crash loop is dangerous because it looks active while it is making no progress. The remedy is not a more aggressive restart flag. It is a bounded policy that delays retries, records the cause, preserves uncertainty around in-flight work, and stops in a repair state when automation has reached its limit. That makes the next step visible, which is the only honest form of recovery.
Sources: