> ## 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.

> ## Agent Instructions
> To act on a user's behalf in Guild, use the Guild REST API at https://api.guild.ai/v1.
> The OpenAPI spec is unauthenticated: https://docs.guild.ai/openapi.json (or openapi.yaml).
> Authenticate with an account API key, sent as HTTP Basic (key id as username, secret as password) or as `Authorization: Bearer <api_key_id>:<api_key_secret>`. See https://docs.guild.ai/api-reference/introduction#authentication.
> To run one agent on demand without account-wide access, use an API trigger instead: https://docs.guild.ai/platform/api-triggers.
> To search these docs from an MCP client, connect to https://docs.guild.ai/mcp. The full page index is https://docs.guild.ai/llms.txt.

# Errors and troubleshooting

> Look up a Guild error by status code or message text: public API and OAuth responses, CLI errors, and agent limits, with the fix for each.

This page lists the errors Guild returns and what to do about each one. Search it for the status code or the exact message text you received. It covers the public API at `https://api.guild.ai/v1`, the OAuth endpoints, the Guild CLI, and limits that stop an agent while it runs.

## API error format

The public API returns errors as JSON with the matching HTTP status when the request accepts JSON. Send `Accept: application/json` or `*/*` (curl's default); a request with no `Accept` header gets an HTML error page instead.

```json theme={null}
{
  "error": "Unauthorized",
  "message": "Not authenticated"
}
```

* `error` is the name of the error, such as `InvalidInputError`, `NotFound`, or `Conflict`. Branch on the HTTP status rather than this name.
* `message` explains what went wrong. Read it before changing the request; it usually names the field, scope, or entity at fault.

Every response carries an `X-Request-ID` header. Include it when you contact Guild support about a failed request.

An unexpected server error usually returns `500` with a `message` and no `error` field:

```json theme={null}
{
  "message": "Something went wrong"
}
```

## API status codes

| Status | `error` | Example `message` | Cause | What to do |
| - | - | - | - | - |
| `400` | `InvalidInputError` | A validation report naming each failed field and the reason, such as `Field required` | A body field or query parameter is missing or invalid, or the body was sent without `Content-Type: application/json`. | Fix each field the message names, then resend. |
| `400` | `BadRequest` | `The browser (or proxy) sent a request that this server could not understand.` | The body is marked as JSON but can't be parsed. | Send a valid JSON body. |
| `401` | `Unauthorized` | `Not authenticated` | The request carried no credential, or one Guild couldn't read as an API key. | Send the whole `<api_key_id>:<api_key_secret>` string as a Bearer token or with HTTP Basic. See [Authentication](/api-reference/introduction#authentication). |
| `401` | `Unauthorized` | `Invalid API key` | The key ID is well formed, but the secret is wrong or the key was revoked. | Copy the full key again, or [create a new key](/platform/api-keys#create-a-key). |
| `401` | `Unauthorized` | `Invalid OAuth token` | The OAuth access token expired or was revoked. | Get a new access token from the [token endpoint](#oauth-token-endpoint) with your refresh token, or authorize again. |
| `401` | `Unauthorized` | `This credential cannot access this endpoint` | The endpoint doesn't accept API keys or OAuth tokens. | Use an endpoint from the [API reference](/api-reference/introduction). |
| `403` | `InsufficientScope` | `This credential lacks the agents:write scope` | The key or token is valid but lacks the scope the endpoint requires. The `WWW-Authenticate` header names the missing scope. | Create a key with that scope. Each endpoint lists the scope it needs. See [Scopes](/api-reference/introduction#scopes). |
| `403` | `Forbidden` | Varies | The key's account can't perform this action, even with the right scope. | Check that the key's account owns or administers the target. |
| `404` | `NotFound` | `The requested URL was not found on the server. If you entered the URL manually please check your spelling and try again.` | The path is wrong, or the entity doesn't exist or the key can't see it. Guild returns `404` rather than `403` for reads it denies. | Check the path and every ID in it. Use the top-level `id` from the response that created the entity. |
| `405` | `MethodNotAllowed` | `The method is not allowed for the requested URL.` | The endpoint doesn't support this HTTP method. | Check the method in the [API reference](/api-reference/introduction). |
| `409` | `Conflict` | `Agent "<owner>~<name>" already exists. Please choose a different name.` | An agent with that name already exists in the account. | Choose a different name. |
| `409` | `Conflict` | `Version is already published` | The version was already published. | Save a new version and publish that one. |
| `409` | `Conflict` | `Version is being published, try again later.` | Another request is publishing the same version. | Wait, then check the version before you retry. |
| `409` | `Conflict` | `Cannot publish: validation has not passed` | The version hasn't passed validation. | Wait for validation to finish, or fix the errors and save a new version. |
| `409` | `Conflict` | `Agent must be READY before it can be configured.` | The agent is still being set up. | Wait for the agent to be ready, then retry. |
| `429` | `TooManyRequests` | `This user has exceeded an allotted request count. Try again later.` | Too many requests from this key or IP address in a short window. | Wait, then retry with backoff. |
| `5xx` | Varies | `Something went wrong` | Guild failed to process the request. | Retry with backoff. If it keeps failing, contact support with the `X-Request-ID`. |

### Retrying requests

* **Retry `5xx` and network errors** with exponential backoff. The Guild CLI retries the same failures.
* **On `429`, wait before you retry.** The response has no `Retry-After` header. Request counts reset each minute.
* **Don't resend an unchanged `4xx` request.** It fails the same way until you fix the request, the credential, or the state the message names.
* **Check before you retry a write.** If a publish or create timed out, the server may have finished it. Read the entity first, so a retry doesn't fail with `409`.

## OAuth token endpoint

`POST https://api.guild.ai/v1/oauth/token` follows [RFC 6749](https://www.rfc-editor.org/rfc/rfc6749#section-5.2). Errors use `error` and `error_description` instead of `message`:

```json theme={null}
{
  "error": "invalid_grant",
  "error_description": "Refresh token is invalid or expired"
}
```

| Status | `error` | `error_description` | What to do |
| - | - | - | - |
| `400` | `invalid_request` | The first failed field, for example `Field required` | Send every parameter the grant type needs. |
| `400` | `unsupported_grant_type` | `grant_type must be authorization_code or refresh_token` | Use `authorization_code` or `refresh_token`. |
| `400` | `invalid_grant` | `Authorization code is invalid or expired` | Start the authorization flow again. A code works once, for the client and redirect URI that requested it, with the matching PKCE verifier. |
| `400` | `invalid_grant` | `Refresh token is invalid or expired` | Authorize again. A refresh token works once; use the new one each refresh returns. Reusing a spent refresh token revokes every token from that authorization. |
| `401` | `invalid_client` | `Client authentication failed` | Send the `client_id` returned when you registered the client, and its secret if it has one. |

`POST https://api.guild.ai/v1/oauth/register` returns `400 InvalidInputError` with a `message` that lists each failed field. It returns `429` when one IP address registers more than 10 clients in an hour.

## CLI errors

Run `guild doctor` first. It checks your login, the server connection, your default workspace, the agent directory, and Git, and suggests a fix for each failure. See [`guild doctor`](/cli/commands/doctor).

| Message | Cause | Fix |
| - | - | - |
| `Not authenticated. Please log in first.` | No login found, or Guild rejected the credential with `401`. | Run `guild auth login`. |
| `Not authenticated. Run: guild auth login` | The command found no login, or Guild rejected the request with `401`. | Run `guild auth login`. |
| `This operation requires authentication.` | No login found, or Guild rejected the credential with `401`. | Run `guild auth login`, or set `GUILD_API_KEY`. |
| `Your authentication token is invalid or expired. Please run: guild auth login` | The stored login expired. The CLI clears it. | Run `guild auth login`. |
| `GUILD_API_KEY was rejected (...). The key may be invalid, or this command may not accept API keys yet.` | Guild rejected the key in `GUILD_API_KEY`. The text in parentheses is the server's message. | Check that the variable holds the whole `<api_key_id>:<api_key_secret>` string. If the message is `This credential cannot access this endpoint`, unset `GUILD_API_KEY` and use `guild auth login`. |
| `This credential lacks the <group>:<access> scope` | The API key in `GUILD_API_KEY` lacks a scope the command needs. | Create a key with that scope. [`guild agent save`](/cli/commands/agent#save-from-your-own-repository) needs `agents:write`. |
| `Authorization succeeded, but the token could not be saved` | The CLI couldn't write the token to the keyring or its fallback file. | Make sure the config directory (`GUILD_CONFIG_DIR`, or `~/.guild`) exists and is writable, then run `guild auth login` again. |
| `No default workspace configured` | The command needs a workspace and none is set. | Run `guild workspace select`, or pass `--workspace <workspace-id>`. |
| `No workspace specified. Run: guild workspace select` | Same as above. | Run `guild workspace select`, or pass `--workspace`. |
| `Workspace not found` | The workspace doesn't exist or you can't see it. | Run `guild workspace list` and use an ID from it. |
| `Agent not found` | The agent doesn't exist or you can't see it. | Run `guild agent list`. |
| `No agent ID provided and not in an agent directory` | The command needs an agent and the current directory has no `guild.json`. | Pass the agent ID, or `cd` into the agent directory. |
| `Not in an agent directory` | The command only runs inside an agent directory. | Run `guild agent init --name <name>` or `guild agent clone <agent-id>`, then run the command there. |
| `No changes to save` | The files match your last save. | Edit the agent, then save again. |
| `Version conflict` | Someone saved a newer version since your last save. | Review the newer version. To overwrite it with your local files, rerun with `--force`. |
| `Cannot publish: validation is still in progress` | Validation hasn't finished. | Run `guild agent publish --wait`. |
| `Cannot publish: validation failed` | The version failed validation. | Run `guild agent logs` to see the errors, fix them, and save a new version. |
| `Version <id> is already published` | The latest version is already published. | Save a new version first. |
| `The resource you are trying to create already exists` | Guild returned `409` with no message. | Choose a different name, or use the existing resource. |
| `Cannot connect to Guild servers` | The CLI couldn't reach Guild. | Check your network connection, then run `guild doctor`. |
| `The connection was aborted before receiving a response` | The request timed out after 30 seconds, or the connection dropped. | Retry. If it keeps happening, check your network and run `guild doctor`. |
| `Server took too long to respond` | The connection timed out at the network level. | Retry. If it keeps happening, check your network and run `guild doctor`. |
| `Could not resolve server hostname` | DNS lookup failed. | Check your internet connection and DNS settings. |
| `Something went wrong` | Guild hit a server error. | Retry. If it persists, rerun with `--debug` and contact support. |

When an update is available and the CLI doesn't install it automatically, it prints `Update available: <current> → <latest>  Run: npm install -g @guildai/cli`. This is a notice, not an error.

Commands exit with code `1` on error. In JSON mode (`--mode json`), most errors go to stderr as `{"success": false, "error": "...", "details": "..."}`.

## Agent and session errors

Runtime limits stop an agent that runs away. The agent's LLM call or task fails with the status and message below.

| Message or result | Cause | See |
| - | - | - |
| `413 Request Entity Too Large` | Saved state exceeds 8 MiB. | [State size](/reference/limits#state-size) |
| `exceeded LLM request size limit for this task` | One LLM request is larger than 8 MiB. | [LLM execution budgets](/reference/limits#llm-execution-budgets) |
| `exceeded LLM call limit for this execution tree` | The execution tree made too many LLM calls. | [LLM execution budgets](/reference/limits#llm-execution-budgets) |
| `exceeded LLM token limit for this execution tree` | The execution tree used too many tokens. | [LLM execution budgets](/reference/limits#llm-execution-budgets) |
| `exceeded agent task limit for this execution tree` | The agent started too many sub-agent tasks. | [Unlimited power mode](/reference/limits#unlimited-power-mode) |
| `exceeded tool fan-out limit for this task` | One task made too many tool calls. | [Unlimited power mode](/reference/limits#unlimited-power-mode) |
| `<SCOPE> budget exceeded for '<name>'` | A workspace, agent, or user monthly spend budget is used up. | [Spend budgets](/reference/limits#spend-budgets) |
| `Agent ran too many synchronous steps without yielding` | The agent looped without an `await`. | [Synchronous step budget](/reference/limits#synchronous-step-budget) |
| `TURN_TIMEOUT:` | A turn ran past the wall-clock ceiling. | [Turn timeout](/reference/limits#turn-timeout) |

The `exceeded ...` and budget messages arrive as `429 Too Many Requests`. Retrying the same run won't help; change the agent, raise the limit, or wait for the budget to reset.

## Related pages

* [API reference introduction](/api-reference/introduction)
* [API keys](/platform/api-keys)
* [Execution limits](/reference/limits)
* [CLI troubleshooting](/cli/getting-started#troubleshooting)