> ## Documentation Index
> Fetch the complete documentation index at: https://docs.guild.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting agents

> Diagnose and fix common runtime errors in Guild agents.

This page covers runtime errors you may encounter when running Guild agents and how to resolve them.

## Synchronous infinite loops and step budgets

If an agent runs too many synchronous steps in a tight loop without yielding — for example, a `while (true)` loop with no `await` or async operations — the runtime triggers a circuit breaker to prevent an out-of-memory crash.

By default, the runtime limits consecutive budget refreshes to **10**, which corresponds to 10,000 synchronous steps without yielding.

### Error message and stack trace

When the limit is exceeded, execution stops with a `UserError`:

```
Your agent ran too many synchronous steps without yielding (10000+ steps) and had to be stopped.
When stopped, the agent was here:
  at scope(2) step=1 { items=["x","x","x",...] }
  at scope(1) { _input={"text":"trigger"}, _task={...} }
```

Because compiled state machines do not retain original function names in their runtime frames, the trace shows compiled scope IDs and snapshots of local variables:

* `scope(N)` — the scope level in the compiled output.
* `{ variable=value }` — a snapshot of local variables in that scope when execution stopped. Use this to identify which variables are growing or where the loop is stuck.

### Configuring the limit

If your agent performs legitimate heavy synchronous processing and requires a higher budget, you can raise the cap:

* **Environment variable:** Set `GUILD_MAX_BUDGET_REFRESHES` to a higher integer. See [Environment variables](/reference/environment-variables).
* **Runtime knob:** Set `runtime.agent.max_budget_refreshes`. See [Runtime knobs](/reference/knobs).