> ## Documentation Index > Fetch the complete documentation index at: https://docs.labelbox.com/llms.txt > Use this file to discover all available pages before exploring further. # Troubleshooting > Match a Managed Agents symptom or error code to its cause and fix, for sign-in, keys, organizations, billing, environments, MCP servers and credentials, sessions, and grading. Start with the stable field, not the message: the response's `code`, a session's `failure.code`, or a setup run's `failure_code`. Messages can change; codes don't. HTTP errors are flat objects with required `code` and `message` fields and optional `details`. Every code is listed in [Errors](/managed-agents/errors). ## Sign-in and the console | Symptom | Cause | Fix | | --------------------------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------ | | **Sign-in is limited to approved accounts.** | Your account isn't approved for access. | Sign in with an approved account. | | **Verify your email address with your provider, then sign in again.** | Your identity provider hasn't verified your email address. | Verify it with the provider, then sign in again. | | **That sign-in link is no longer valid.** | The sign-in attempt can no longer be completed. | Start again from the sign-in page. | ## API keys and authentication | Code or symptom | Cause | Fix | | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `401 unauthorized` | The `Authorization` header is missing or malformed, or the key expired, was revoked, or is inactive. | Send `Authorization: Bearer $RECURSION_API_KEY`. Check the key's status under **API keys**. | | `401` right after exporting a key | The key was exported in a different shell, or copied with extra characters. | Export it in the shell that runs your code, then check it starts with `rma_`. | | `400 invalid_request` mentioning `x-organization-id` | A tenant-scoped key sent no `x-organization-id`. | Add `x-organization-id: default` or an organization id, or use an organization-scoped key. See [API keys](/managed-agents/api-keys). | | `404 not_found` on every request | `x-organization-id` names an organization you can't reach. | Use `default`, or remove the header for an organization-scoped key. | | A key stopped working without being revoked | It expired. | Check its status, then create a new key. | | `503 service_unavailable` before anything ran | The key couldn't be checked right now. | Retry shortly. | ## Organizations and roles | Code or symptom | Cause | Fix | | --------------------------------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `403 forbidden` on create, update, or delete | Your organization role is read-only. | See [Organizations and roles](/managed-agents/organizations-and-roles). Use an account or key with the developer or admin role. | | `403 forbidden` when testing an environment's setup | Testing setup needs create and update permission, because it provisions compute. | See [Organizations and roles](/managed-agents/organizations-and-roles). Use an account or key with the developer or admin role. | ## Billing | Symptom | Cause | Fix | | -------------------------------------------------------------- | --------------------------------------------------------------- | ----------------------------------------------------------- | | **Billing** isn't in the sidebar | Your tenant role isn't billing, admin, owner, or primary owner. | Use an account with one of those roles. | | "The card was declined. Replace it in Stripe, then try again." | The bank declined the charge. | Click **Manage cards**, choose another card, and buy again. | See [Billing](/managed-agents/billing). ## Environments and setup | Code or symptom | Cause | Fix | | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | `422 environment_not_verified` on session start | The setup script has never passed, failed, changed since it passed, or is still being tested. `details.next_action` names the call to make. | Run a setup test, wait for `verified` with `stale: false`, then start again. | | Setup test fails with `phase: setup` | The script exited with an error or timed out. | Read `failed_line`, `failed_command`, `exit_code`, `hint`, and `stderr_tail`. Fix the script and test again. | | Setup test fails in another phase | A temporary problem preparing compute. | Retry once before changing the script. | | `429 setup_run_limit` | Your organization has too many setup runs in flight. | Wait for one in `details.in_flight`, or cancel it. | | `409 setup_run_in_progress` | A setup test is already running for this environment. | Wait for `details.setup_run_id`, or cancel it. | | `428 precondition_required` on an environment update | You changed a stored network policy, or turned on privileged access, without `expected_access`. | Read the environment and send its current access settings. | | Package installs fail in setup or in the session | The environment has no internet access. | Allow the needed destinations, or set **Internet access** to **Enabled**, then test again. | See [Environments](/managed-agents/environments). ## Integrations | Code or symptom | Cause | Fix | | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | **Add integration** is missing on **Integrations** | Your role can view integrations but not add them. | Ask someone with the organization developer or admin role. | | An app's row stays **Pending setup** | Nobody finished signing in to the app. | Click **Connect** on the row and finish the sign-in. | | An app's row shows **Revoked**, or the agent can't reach an app | The app no longer accepts the sign-in. | Reconnect the app on **Integrations**. See [Reconnect an app](/managed-agents/integrations#reconnect-an-app). | | The agent can't use a tool in an app | The tool isn't on the app's allow-list, or the app isn't granted to the agent. | Add the tool with **Tools** on the app's row, or grant the app to the agent, then start a new session. | | Sessions stopped using an app after a catalog update | A tool on the allow-list was reclassified or removed. | Open **Tools** on the app's row, click **Remove**, then **Save tools**. | | **Reconnect first** when granting an app to an agent | The connection isn't active. | Connect or reconnect it on **Integrations**. | | `400 invalid_request` on `built_in_integrations` | More than 25 entries, a non-empty `tools`, or a connection that isn't an active built-in integration with at least one tool. | Read `message` and fix the entry. See [Grant apps to an agent](/managed-agents/integrations#grant-apps-to-an-agent). | \| `git` or `gh` is unauthenticated in a session | The agent version has no GitHub grant, or the session started before you saved it. | Grant GitHub on the agent and start a new session. See [GitHub access](/managed-agents/github). | \| `git` can't reach `github.com` | The environment's network policy blocks GitHub. | Allow the GitHub hosts. See [Allow GitHub hosts](/managed-agents/github#allow-github-hosts). | See [Integrations](/managed-agents/integrations#what-can-go-wrong) for every integration error. ## Memory, files, and automations | Symptom or code | Cause | Fix | | -------------------------------------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | An agent's memory shows **Updates delayed** | A learning run failed. | Nothing to do. It retries on its own, and existing memories stay available. See [Memory](/managed-agents/memory). | | `409 content_sha256_mismatch` updating a memory | Someone changed it after you read it. | Read it again and retry with the new hash. | | `413 file_quota_exceeded` on upload | Your organization's files are at their storage quota. | Delete files you no longer need. See [Files](/managed-agents/files). | | The agent can't find an attached file | It was attached mid-turn. | It's in place on the next tool call and visible from the next turn. | | A deliverable isn't on the session's **Files** tab | The agent saved it outside the deliverables folder. | Ask for it by name as a deliverable. See [Deliverables and artifacts](/managed-agents/artifacts). | | An automation never starts a run | It's paused, its trigger is off, or its event source is paused. | Resume the automation and the source. See [Automations](/managed-agents/automations). | | A webhook delivery returns `401 unauthorized` | The signature didn't match the source's signing secret. | Sign the exact body bytes with the secret in the source's vault. | | An automation run is `failed` | The session couldn't start. | Read the run's `error`, fix the named field or resource, and run it again. | ## MCP servers and credentials | Code or symptom | Cause | Fix | | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | MCP tools are missing from a session | The server couldn't be reached, its handshake failed, or no granted credential matched its URL. | Probe the server and fix the URL, server, or vault grant, then start a new session. A running session doesn't pick up new tools. See [MCP servers](/managed-agents/mcp-servers). | | An environment-variable secret shows up in the transcript | The agent printed it. Any command in the sandbox can read these secrets. | Rotate the secret. Prefer an MCP credential, which never enters the sandbox. See [Security](/managed-agents/security). | | Session fails with `credential_resolution_failed` | A granted credential couldn't be opened, or was deleted. | Check the session's vaults and `credential_refs`. | ## Sessions | Code or symptom | Cause | Fix | | ------------------------------------------------------------ | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Session stays `queued` | The agent is at its `max_concurrent_sessions` cap. Child sessions don't count. | Wait for a root session to finish, hard stop one you don't need, or raise the cap. See [Usage and cost](/managed-agents/usage-and-cost). | | Session stays `provisioning` | Compute is being prepared. | Read the session, not just its events. After 5 minutes it fails with `sandbox_provision_timeout`; resume it or start again. | | No events yet, but the session is `running` | The event stream is written separately and can lag the session record. | Trust `status` and `execution_state` from `getSession`. | | Session `failed` | See `failure.code`, `failure.category`, and `failure.retryable`. | `transient`: send a follow-up to resume. `caller_error`: fix the configuration first. `internal`: report the `session_id`. See [Session failure codes](/managed-agents/errors#session-failure-codes). | | `422 sandbox_provider_disabled` | The request names a runtime this deployment doesn't offer for new work. | Use the **Agent runner** runtime (`runs`). | | Session is `idle` with `end_turn` but the work is incomplete | The agent stopped on its own. `end_turn` doesn't mean correct. | Send guidance, or add an outcome so a grader checks the work. | | `409 idempotency_conflict` | You reused an `Idempotency-Key` with a different request. | Use a new key for a new request. | | Event stream returns `503 service_unavailable` | The service is at event-stream capacity. | Close streams you no longer need, then retry with backoff. | | Event stream disconnects | Networks drop long connections. | Reconnect with `Last-Event-ID` or `after_event_id` set to the last event you received. See [Events](/managed-agents/events). | | A follow-up after a hard stop starts from a clean workspace | Hard stop tears down the sandbox. | Use **Interrupt** instead when you want to keep the sandbox. | ## Grading | Symptom | Cause | Fix | | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Outcome never reaches `satisfied` | A criterion can't be met, can't be checked on its own, or needs facts the grader can't see. With no `max_iterations`, the agent keeps revising. | Read the newest pass's failed criteria and their `rationale`. Hard stop if needed, then define a new outcome with checkable criteria and a finite `max_iterations`. See [Outcomes](/managed-agents/outcomes). | | Outcome ends `max_iterations_reached` | A criterion still failed on the last allowed pass. | Tighten the prompt or the rubric, then define a new outcome. | | Outcome ends `failed` | The rubric couldn't be graded. | Rewrite it as a list of independent, checkable criteria. | | `stop_reason: grader_failed` | A grading pass produced no usable verdict. | Send a follow-up to retry. | | Defining an outcome returns `400 invalid_request` on `outcome` | The session already has an active outcome. Only one runs at a time. | Wait until it's graded, then define the next one. | | The grader ignores facts from your message | The grader never sees the opening `message`, only the outcome's objective and rubric. | Put facts the grader must check in the outcome's `description` or the rubric. | ## Rate limits and server errors | Code | Cause | Fix | | ------------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `429 rate_limit_exceeded` | Too many requests from you, across all your keys and console use. | `Retry-After` tells you how long to wait, not whether replay is safe. Retry only when the operation's strategy in **Endpoints** permits it and `details.retryable` is not `false`. Numeric limits aren't published. | | `503` | A dependency is temporarily unavailable, or a keyed request could not reserve its idempotency key. | Read `code` and `details.retryable`. Retry only when the operation's strategy in **Endpoints** permits it. `idempotency_unavailable` did not run the request, so resend the same key and request bytes. | | `504 gateway_timeout` | The request took too long and may have run. | Retry a keyed mutation only with the same key and request bytes. Read the resource before deciding whether to repeat any other write. | | `500 internal_error` | An unexpected failure. | Retry reads once. For a write, follow the operation's strategy in **Endpoints**. If it persists, report the request id. | ## What to include in a support request | Field | Why | | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | `code` | Selects the recovery path. Do not match `message`. | | `details.field` | When present, names the request field, query parameter, or header at fault. | | `details` | When present, holds code-specific state, measured values, limits, and next actions. | | `details.retryable` | When present, advises whether the failure is transient. It does not override the operation's retry strategy. | | `details.requestId`, or the `x-request-id` header | Lets support find the request. | | `session_id` | Identifies the full session tree and its events. | | `failure.code` and `failure.phase` | Say which stage of a session failed. | | `setup_run_id` | Identifies a setup test and its log. | | `recursion-organization-id` response header | Confirms which organization the request ran in. | Never include an API key or secret value in a support request. ## Next steps Every error and failure code with retry guidance. Every limit you can hit. Decode statuses, stop reasons, and results. Retries, idempotency, and paging.