Execution limits

Guild enforces hard runtime limits that act as runaway backstops. They protect against infinite loops, unbounded state growth, and runaway LLM billing costs. These are not normal-traffic thresholds — a healthy agent run stays well below them. This page describes each limit, the error you receive when you cross it, how usage is counted, and how to diagnose and configure it.

State size

Every call to task.save() serializes your agent’s state and persists it through the runtime. The serialized state has a maximum size of 8 MiB.

The SDK checks the serialized size before sending it and fails fast with a local error when the state exceeds 8 MiB, so you see the problem in your agent code rather than as a network error.
The runtime enforces the same 8 MiB ceiling on the save-state endpoint and returns HTTP 413 Request Entity Too Large when a request exceeds it. The runtime limit is authoritative.

If you hit this limit, reduce what you persist. Store identifiers or summaries instead of full payloads, and avoid accumulating large arrays or message histories in state. See State for guidance on what to persist.

LLM execution budgets

Guild meters LLM usage per execution and stops an agent that exceeds any of these budgets. When a budget is exceeded, the LLM proxy returns HTTP 429 Too Many Requests and the call fails.

Limit	Value	Applies to
Request payload size	8 MiB	A single LLM request
LLM calls	500	One execution tree
LLM tokens	50,000,000	One execution tree

How usage is counted

The token budget counts input and output tokens only. Cache-read and cache-write tokens are excluded. Reusing a cached prompt across many calls does not consume the token budget, so prompt caching both lowers cost and keeps you under the limit.
The counting window depends on how the execution started. Chat and agent-test roots count from the latest user message, so the call and token budgets reset on each user turn. Trigger roots count across the full execution tree for the entire run.

Synchronous step budget

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 inner() step=12, line 17 { doubledAgain=10, config={...} }
  at middle() step=4, line 22 { doubled=10 }
  at deepStack() step=2, line 26 { longString="yyy...", config={...} }

The runtime stack trace shows named frames with the original function name and source line number for each active scope, along with snapshots of local variables:

at functionName() — the original name of a function scope. Anonymous block, loop, and try scopes fall back to scope(id).
step=N — the compiled step index within that scope.
line L — the source code line number the frame maps to.
{ variable=value } — a snapshot of local variables in that scope when execution stopped. Values are summarized safely: long strings are truncated (for example, "yyy..."), objects are masked as {...}, and so on, so credentials or large datasets do not clutter or leak into the trace. 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.
Runtime knob: Set runtime.agent.max_budget_refreshes. See Runtime knobs.

Turn timeout

A single agent communicate() turn has a wall-clock ceiling. Without it, a turn that backgrounds a command, polls for a result, or runs a wedged tool or command could wait indefinitely and keep the entire session stuck. The default ceiling is 3,600 seconds (1 hour). When a turn exceeds the timeout, the runtime terminates the in-progress command and completes the turn with a TURN_TIMEOUT: result that contains the last-seen session ID. The calling agent resumes the container session with a follow-up message instead of the run failing. Adjust the ceiling with the GUILD_AGENT_TURN_TIMEOUT_SECONDS environment variable. See Environment variables for the full agent runtime configuration.

Error reference

Condition	Result
Saved state exceeds 8 MiB	`413 Request Entity Too Large`
LLM request size, call count, or token budget exceeded	`429 Too Many Requests`
Synchronous step budget exceeded	Execution stops with a `UserError` and a runtime stack trace
Turn exceeds the wall-clock ceiling	Turn completes with a `TURN_TIMEOUT:` result

Reference

Configuration

Execution limits

State size

LLM execution budgets

How usage is counted

Synchronous step budget

Error message and stack trace

Configuring the limit

Turn timeout

Error reference

​State size

​LLM execution budgets

​How usage is counted

​Synchronous step budget

​Error message and stack trace

​Configuring the limit

​Turn timeout

​Error reference

State size

LLM execution budgets

How usage is counted

Synchronous step budget

Error message and stack trace

Configuring the limit

Turn timeout

Error reference