89| `403` with `x-deny-reason: host_not_allowed` in a cloud or routine session | [Network](#host-not-allowed-in-a-cloud-session) |89| `403` with `x-deny-reason: host_not_allowed` in a cloud or routine session | [Network](#host-not-allowed-in-a-cloud-session) |
90| `proxy refused the connection` | [Network](#the-proxy-refused-the-connection) |90| `proxy refused the connection` | [Network](#the-proxy-refused-the-connection) |
91| `403` with `This GraphQL query is not enabled for this session` in a cloud session | [GitHub proxy](/docs/en/cloud-environments#github-proxy) |91| `403` with `This GraphQL query is not enabled for this session` in a cloud session | [GitHub proxy](/docs/en/cloud-environments#github-proxy) |
92| `The cloud environments service returned an empty response` / `The cloud environments service returned a response in an unexpected format` | [Network](#the-cloud-environments-service-returned-an-empty-or-unexpected-response) |
92| `Couldn't reconnect to your Remote Control session` | [Network](#couldnt-reconnect-to-your-remote-control-session) |93| `Couldn't reconnect to your Remote Control session` | [Network](#couldnt-reconnect-to-your-remote-control-session) |
93| `N sessions ended while this machine was offline — the environment was cleaned up on the server and can't be resumed.` | [Network](#sessions-ended-while-this-machine-was-offline) |94| `N sessions ended while this machine was offline — the environment was cleaned up on the server and can't be resumed.` | [Network](#sessions-ended-while-this-machine-was-offline) |
94| `Couldn't share the transcript.` | [Network](#couldnt-share-the-transcript) |95| `Couldn't share the transcript.` | [Network](#couldnt-share-the-transcript) |
96| `The remote session sent a reply this version can't display` | [Network](#the-remote-sent-a-reply-this-version-cant-display) |97| `The remote session sent a reply this version can't display` | [Network](#the-remote-sent-a-reply-this-version-cant-display) |
97| `Prompt is too long` / `Input is too long for requested model` | [Request errors](#prompt-is-too-long) |98| `Prompt is too long` / `Input is too long for requested model` | [Request errors](#prompt-is-too-long) |
98| `Prompt is too long · automatic compaction failed:` | [Request errors](#prompt-is-too-long) |99| `Prompt is too long · automatic compaction failed:` | [Request errors](#prompt-is-too-long) |
100| `Prompt is too long · this conversation is a single exchange` / `A single-exchange conversation cannot be compacted` | [Request errors](#prompt-is-too-long) |
99| `Context limit reached · /compact or /clear to continue` | [Request errors](#prompt-is-too-long) |101| `Context limit reached · /compact or /clear to continue` | [Request errors](#prompt-is-too-long) |
100| `Context limit reached · /clear to continue` | [Request errors](#prompt-is-too-long) |102| `Context limit reached · /clear to continue` | [Request errors](#prompt-is-too-long) |
101| `capability_rejected: prompt_too_long` on a Claude apps gateway session | [Request errors](#prompt-is-too-long) |103| `capability_rejected: prompt_too_long` on a Claude apps gateway session | [Request errors](#prompt-is-too-long) |
110| `Unable to resize image` | [Request errors](#unable-to-resize-image) |112| `Unable to resize image` | [Request errors](#unable-to-resize-image) |
111| `PDF too large` / `PDF is password protected` | [Request errors](#pdf-errors) |113| `PDF too large` / `PDF is password protected` | [Request errors](#pdf-errors) |
112| `Extra inputs are not permitted` | [Request errors](#extra-inputs-are-not-permitted) |114| `Extra inputs are not permitted` | [Request errors](#extra-inputs-are-not-permitted) |
115| `API Error: 400 ... tools.N.custom.input_schema: JSON schema is invalid` | [Request errors](#tool-input-schema-is-invalid) |
113| `There's an issue with the selected model` | [Request errors](#theres-an-issue-with-the-selected-model) |116| `There's an issue with the selected model` | [Request errors](#theres-an-issue-with-the-selected-model) |
114| `Model ... is not a recognized model id` | [Request errors](#model-is-not-a-recognized-model-id) |117| `Model ... is not a recognized model id` | [Request errors](#model-is-not-a-recognized-model-id) |
115| `Claude Opus is not available with the Claude Pro plan` | [Request errors](#claude-opus-is-not-available-with-the-claude-pro-plan) |118| `Claude Opus is not available with the Claude Pro plan` | [Request errors](#claude-opus-is-not-available-with-the-claude-pro-plan) |
134| `` `claude import` is not yet available in this build `` | [Command-line errors](#claude-import-is-not-yet-available-in-this-build) |137| `` `claude import` is not yet available in this build `` | [Command-line errors](#claude-import-is-not-yet-available-in-this-build) |
135| `Could not read Claude Code config` | [Command-line errors](#could-not-read-claude-code-config) |138| `Could not read Claude Code config` | [Command-line errors](#could-not-read-claude-code-config) |
136| `Could not import <server>: <reason>` | [Command-line errors](#could-not-import-a-server-from-claude-desktop) |139| `Could not import <server>: <reason>` | [Command-line errors](#could-not-import-a-server-from-claude-desktop) |
140| `is Anthropic-hosted and doesn't support local OAuth` | [Command-line errors](#anthropic-hosted-and-doesnt-support-local-oauth) |
137| `Error: MCP tool <name> (passed via --permission-prompt-tool) not found` | [Command-line errors](#mcp-permission-prompt-tool-not-found) |141| `Error: MCP tool <name> (passed via --permission-prompt-tool) not found` | [Command-line errors](#mcp-permission-prompt-tool-not-found) |
138| `Shell command failed for pattern "..."`, from `/security-review` or any skill that injects dynamic context | [Command-line errors](#security-review-fails-without-origin-head) |142| `Shell command failed for pattern "..."`, from `/security-review` or any skill that injects dynamic context | [Command-line errors](#security-review-fails-without-origin-head) |
139| `Shell command permission check failed for pattern "..."`, from a skill that injects dynamic context | [Command-line errors](#security-review-fails-without-origin-head) |143| `Shell command permission check failed for pattern "..."`, from a skill that injects dynamic context | [Command-line errors](#security-review-fails-without-origin-head) |
174| `This session has no saved transcript` | [Background session errors](#this-session-has-no-saved-transcript) |178| `This session has no saved transcript` | [Background session errors](#this-session-has-no-saved-transcript) |
175| `terminal host process died — press Enter to restart` / `This session's terminal host process died` | [Background session errors](#terminal-host-process-died) |179| `terminal host process died — press Enter to restart` / `This session's terminal host process died` | [Background session errors](#terminal-host-process-died) |
176| `Session isn't responding` / `Press enter again to restart this session — it isn't responding` | [Background session errors](#session-isnt-responding) |180| `Session isn't responding` / `Press enter again to restart this session — it isn't responding` | [Background session errors](#session-isnt-responding) |
181| `Session <id> was stopped while the respawn was in flight` | [Background session errors](#session-was-stopped-while-the-respawn-was-in-flight) |
177| `This session was running agent '<name>', which is no longer available` | [Background session errors](#session-agent-no-longer-available) |182| `This session was running agent '<name>', which is no longer available` | [Background session errors](#session-agent-no-longer-available) |
178| `CLAUDE_CODE_PROCESS_WRAPPER: launcher ...` | [Background session errors](#claude_code_process_wrapper-launcher-errors) |183| `CLAUDE_CODE_PROCESS_WRAPPER: launcher ...` | [Background session errors](#claude_code_process_wrapper-launcher-errors) |
179| `EUNKNOWN: unknown error, uv_spawn` | [Background session errors](#eunknown-when-starting-a-background-session) |184| `EUNKNOWN: unknown error, uv_spawn` | [Background session errors](#eunknown-when-starting-a-background-session) |
185| `EACCES: permission denied, posix_spawn` | [Background session errors](#eacces-when-starting-a-background-session) |
186| `exited before it became reachable` | [Background session errors](#background-service-exited-before-it-became-reachable) |
180| `Claude Code process exited with code N` | [Wrapper and IDE errors](#claude-code-process-exited-with-code-n) |187| `Claude Code process exited with code N` | [Wrapper and IDE errors](#claude-code-process-exited-with-code-n) |
181| `Could not locate the Claude CLI on PATH` | [Wrapper and IDE errors](#could-not-locate-the-claude-cli-on-path) |188| `Could not locate the Claude CLI on PATH` | [Wrapper and IDE errors](#could-not-locate-the-claude-cli-on-path) |
182| `Restored the code, but skipped N files` | [Rewind warnings](#restored-the-code-but-skipped-files) |189| `Restored the code, but skipped N files` | [Rewind warnings](#restored-the-code-but-skipped-files) |
185| `Transcript saving is off — inherited CLAUDE_CODE_CHILD_SESSION marker` | [Session saving warnings](#transcript-saving-is-off-child-session-marker) |192| `Transcript saving is off — inherited CLAUDE_CODE_CHILD_SESSION marker` | [Session saving warnings](#transcript-saving-is-off-child-session-marker) |
186| `Claude Code's fullscreen renderer didn't finish starting last time on this machine` / `Claude Code's fullscreen renderer has repeatedly failed to start on this machine` | [Configuration warnings](#fullscreen-failed-start-notice) |193| `Claude Code's fullscreen renderer didn't finish starting last time on this machine` / `Claude Code's fullscreen renderer has repeatedly failed to start on this machine` | [Configuration warnings](#fullscreen-failed-start-notice) |
187| `Claude Code exited after an unrecoverable interface error (...)` | [Configuration warnings](#exited-after-an-unrecoverable-interface-error) |194| `Claude Code exited after an unrecoverable interface error (...)` | [Configuration warnings](#exited-after-an-unrecoverable-interface-error) |
195| `Agent descriptions are over the 15.0k-token limit` | [Configuration warnings](#agent-descriptions-are-over-the-15000-token-limit) |
188| `Ignoring N permissions.allow entries from ... this workspace has not been trusted` | [Configuration warnings](#workspace-has-not-been-trusted) |196| `Ignoring N permissions.allow entries from ... this workspace has not been trusted` | [Configuration warnings](#workspace-has-not-been-trusted) |
189| `headersHelper not run — this workspace has no persisted trust` | [Configuration warnings](#headershelper-not-run) |197| `headersHelper not run — this workspace has no persisted trust` | [Configuration warnings](#headershelper-not-run) |
190| `... is not matched by file permission checks` | [Configuration warnings](#is-not-matched-by-file-permission-checks) |198| `... is not matched by file permission checks` | [Configuration warnings](#is-not-matched-by-file-permission-checks) |
1242 1250
1243Before v2.1.238, Claude Code reported a refused tunnel as a generic network error.1251Before v2.1.238, Claude Code reported a refused tunnel as a generic network error.
1244 1252
1253<h3 id="the-cloud-environments-service-returned-an-empty-or-unexpected-response">
1254 The cloud environments service returned an empty or unexpected response
1255</h3>
1256
1257Claude Code requests your [cloud environments](/docs/en/cloud-environments) list at several points, such as when you create a cloud session from the CLI or run [`/remote-env`](/docs/en/cloud-environments#select-an-environment-from-the-cli). When it can't read the server's answer, it shows one of these messages:
1258
1259```text theme={null}
1260The cloud environments service returned an empty response (HTTP 200 with no body). This is usually temporary — try again in a moment.
1261The cloud environments service returned a response in an unexpected format (HTTP 200 with a non-JSON body). This is usually temporary — try again in a moment.
1262The cloud environments service returned a response in an unexpected format (HTTP 200 without a usable environments list). This is usually temporary — try again in a moment.
1263```
1264
1265The server accepted the request but answered with a body that isn't the environments list: empty, not JSON, or JSON without the list. This usually accompanies a service-side disruption and clears on its own. Depending on the surface that requested the list, Claude Code may add a prefix, such as `couldn't list environments:` in the `/remote-env` dialog.
1266
1267**What to do:**
1268
1269* Retry the action. Claude Code requests the list again each time
1270* If the message keeps appearing, check [status.claude.com](https://status.claude.com) for active incidents
1271
1272Before v2.1.236, Claude Code showed a raw JavaScript TypeError instead of these messages.
1273
1245<h3 id="couldnt-reconnect-to-your-remote-control-session">1274<h3 id="couldnt-reconnect-to-your-remote-control-session">
1246 Couldn't reconnect to your Remote Control session1275 Couldn't reconnect to your Remote Control session
1247</h3>1276</h3>
1351 1380
1352Resolve the named error first; `/compact` fails on the same error until you do. Before v2.1.229, a failed automatic compaction surfaced `Prompt is too long` without the cause.1381Resolve the named error first; `/compact` fails on the same error until you do. Before v2.1.229, a failed automatic compaction surfaced `Prompt is too long` without the cause.
1353 1382
1383A single-exchange conversation has no earlier turns to summarize. When automatic compaction would have run on one, Claude Code skips the attempt and explains what fills the request instead. When the API doesn't report token counts in its error, the message reads:
1384
1385```text theme={null}
1386Prompt is too long · this conversation is a single exchange and cannot be compacted — the request size comes mostly from system prompt, tool definitions, or attachments.
1387```
1388
1389When the API reports token counts in its error, Claude Code compares them with its own estimate of the conversation's size to tell which is most of the request: the conversation's own content, or the system prompt, tool definitions, and attachment content that Claude Code sends with it. When the conversation's own content is most of the request, the message reads:
1390
1391```text theme={null}
1392Prompt is too long · the request is ~<request tokens> tokens (limit <limit>) and this conversation's own content is most of it. A single-exchange conversation cannot be compacted; start with less content (smaller files or pasted text).
1393```
1394
1395When most of the request is outside the conversation, the message reads:
1396
1397```text theme={null}
1398Prompt is too long · the request is ~<request tokens> tokens (limit <limit>) but this conversation is only ~<conversation tokens> tokens — the rest is system prompt, tool definitions, and attachment content. A single-exchange conversation cannot be compacted; reduce attached files/tools or start with less context.
1399```
1400
1401Before v2.1.162, Claude Code attempted the compaction anyway and surfaced the bare `Prompt is too long` when it failed.
1402
1354**What to do:**1403**What to do:**
1355 1404
1356* Run `/compact` to summarize earlier turns and free space, or `/clear` to start fresh1405* In a multi-turn conversation, run `/compact` to summarize earlier turns and free space, or `/clear` to start fresh. A single-exchange conversation can't be compacted, so shrink the request instead
1357* Run `/context` to see a breakdown of what is consuming the window: system prompt, tools, memory files, and messages1406* Run `/context` to see a breakdown of what is consuming the window: system prompt, tools, memory files, and messages
1358* Disable MCP servers you are not using with `/mcp disable <name>` to remove their tool definitions from context1407* Disable MCP servers you are not using with `/mcp disable <name>` to remove their tool definitions from context
1359* Trim large `CLAUDE.md` memory files, or move instructions into [path-scoped rules](/docs/en/memory#path-specific-rules) that load only when relevant1408* Trim large `CLAUDE.md` memory files, or move instructions into [path-scoped rules](/docs/en/memory#path-specific-rules) that load only when relevant
1380 1429
1381**What to do:**1430**What to do:**
1382 1431
1383* Run `/compact` to summarize earlier turns and free space, or `/clear` to start fresh1432* In a multi-turn conversation, run `/compact` to summarize earlier turns and free space. To start fresh instead, run `/clear`
1384* For more ways to reduce usage, see [Prompt is too long](#prompt-is-too-long)1433* For more ways to reduce usage, see [Prompt is too long](#prompt-is-too-long)
1385 1434
1386Before v2.1.216, `/context` showed usage above 100% with no warning line explaining what that meant or how to recover.1435Before v2.1.216, `/context` showed usage above 100% with no warning line explaining what that meant or how to recover.
1489* Configure your gateway to forward the `anthropic-beta` header. See [feature pass-through](/docs/en/llm-gateway-protocol#feature-pass-through) for what gateways must forward.1538* Configure your gateway to forward the `anthropic-beta` header. See [feature pass-through](/docs/en/llm-gateway-protocol#feature-pass-through) for what gateways must forward.
1490* As a fallback, set [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](/docs/en/env-vars) before launching. [Disable pre-release capabilities](/docs/en/llm-gateway-protocol#disable-pre-release-capabilities) covers the exact scope.1539* As a fallback, set [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](/docs/en/env-vars) before launching. [Disable pre-release capabilities](/docs/en/llm-gateway-protocol#disable-pre-release-capabilities) covers the exact scope.
1491 1540
1541### Tool input schema is invalid
1542
1543A tool in the request declared an `input_schema` that fails the API's JSON Schema validation, so the API rejected the whole request. The number after `tools.` is the failing tool's position in the request's tool list, not a name you can look up.
1544
1545```text theme={null}
1546API Error: 400 ... tools.N.custom.input_schema: JSON schema is invalid
1547```
1548
1549Claude Code [excludes MCP tools whose input schema would fail this validation](/docs/en/mcp#tools-with-invalid-input-schemas) when it loads a server's tools, so requests normally never include one. On a deployment that doesn't receive the remote configuration that enables the exclusion, Claude Code records in the server's log which tool would be rejected but sends it anyway, so this error can still occur. The error can also occur for a tool whose schema declares a JSON Schema dialect other than draft 2020-12 in `$schema`: Claude Code doesn't check those schemas against the JSON Schema meta-schema, though it still excludes one with an invalid top-level property name.
1550
1551Before v2.1.216, no deployment ran the exclusion checks.
1552
1553**What to do:**
1554
1555* If your Claude Code version is earlier than v2.1.216, run `claude update`.
1556* Remove or [disable](/docs/en/mcp#disable-a-server-without-removing-it) the MCP server that declares the invalid schema. The error names the tool only by position. On v2.1.216 or later, check each server's log for a line naming a tool whose input schema would be rejected. If no log names one, disable servers one at a time.
1557* If you maintain the server, fix the tool's `input_schema`. The schema must be valid JSON Schema, and top-level property names must be 1 to 64 characters long and use only ASCII letters and digits, `_`, `.`, and `-`. See [Tools with invalid input schemas](/docs/en/mcp#tools-with-invalid-input-schemas).
1558
1492<h3 id="theres-an-issue-with-the-selected-model">1559<h3 id="theres-an-issue-with-the-selected-model">
1493 There's an issue with the selected model1560 There's an issue with the selected model
1494</h3>1561</h3>
1842* Rename the server in `claude_desktop_config.json` to use only letters, numbers, hyphens, and underscores, then run `claude mcp add-from-claude-desktop` again1909* Rename the server in `claude_desktop_config.json` to use only letters, numbers, hyphens, and underscores, then run `claude mcp add-from-claude-desktop` again
1843* Add that server directly with `claude mcp add` or `claude mcp add-json` under a valid name. See [Import MCP servers from Claude Desktop](/docs/en/mcp#import-mcp-servers-from-claude-desktop).1910* Add that server directly with `claude mcp add` or `claude mcp add-json` under a valid name. See [Import MCP servers from Claude Desktop](/docs/en/mcp#import-mcp-servers-from-claude-desktop).
1844 1911
1912<h3 id="anthropic-hosted-and-doesnt-support-local-oauth">
1913 Server is Anthropic-hosted and doesn't support local OAuth
1914</h3>
1915
1916You started a sign-in for an MCP server whose URL points at an Anthropic-hosted connector host that authenticates through a third-party identity provider. These hosts include `microsoft365.mcp.claude.com`, `gmail.mcp.claude.com`, and `gcal.mcp.claude.com`. Claude Code refuses to start its local OAuth flow for these hosts from both the `/mcp` panel and `claude mcp login`, because [their sign-in works only through claude.ai](/docs/en/mcp#use-mcp-servers-from-claude-ai).
1917
1918```text theme={null}
1919"gmail" is Anthropic-hosted and doesn't support local OAuth. Connect it via Settings → Connectors on claude.ai (requires `claude login`), then it'll be available here automatically.
1920```
1921
1922Claude Code matches these hosts by URL, so the message appears when a server you added with `claude mcp add` or in `.mcp.json` points at one of them.
1923
1924**What to do:**
1925
1926* Remove your entry with `claude mcp remove <name>`, so it can't hide the claude.ai connector at the same URL
1927* After removing it, connect the service at [claude.ai/customize/connectors](https://claude.ai/customize/connectors), while signed in to the account you use in Claude Code. Once connected, [the connector appears in Claude Code automatically](/docs/en/mcp#use-mcp-servers-from-claude-ai) if your active authentication method is a claude.ai subscription login
1928
1845### MCP permission prompt tool not found1929### MCP permission prompt tool not found
1846 1930
1847The tool you passed to [`--permission-prompt-tool`](/docs/en/cli-reference#cli-flags) wasn't among the connected MCP tools when the run first needed a permission decision, either because its server never connected or because no connected server exposes a tool by that name. Claude Code still sends your prompt: the [non-interactive](/docs/en/headless) run exits with this error, and exit code 1, on the first tool call that needs approval, so it produces no answer even though the request was made. Before the first prompt, Claude Code waits up to the per-server connection timeout of 30 seconds set by [`MCP_TIMEOUT`](/docs/en/env-vars) for that server to connect. Before v2.1.206, startup didn't wait for the server to finish connecting, so a slow-starting but healthy server produced this error too.1931The tool you passed to [`--permission-prompt-tool`](/docs/en/cli-reference#cli-flags) wasn't among the connected MCP tools when the run first needed a permission decision, either because its server never connected or because no connected server exposes a tool by that name. Claude Code still sends your prompt: the [non-interactive](/docs/en/headless) run exits with this error, and exit code 1, on the first tool call that needs approval, so it produces no answer even though the request was made. Before the first prompt, Claude Code waits up to the per-server connection timeout of 30 seconds set by [`MCP_TIMEOUT`](/docs/en/env-vars) for that server to connect. Before v2.1.206, startup didn't wait for the server to finish connecting, so a slow-starting but healthy server produced this error too.
2436* From the shell, run `claude stop <id>`, then `claude attach <id>`2520* From the shell, run `claude stop <id>`, then `claude attach <id>`
2437* For a shell-command row, press `Ctrl+X` in agent view or run `claude stop <id>` to stop it; dispatch the command again to rerun it2521* For a shell-command row, press `Ctrl+X` in agent view or run `claude stop <id>` to stop it; dispatch the command again to rerun it
2438 2522
2523### Session was stopped while the respawn was in flight
2524
2525You opened a [background session](/docs/en/agent-view) whose process wasn't running, and while Claude Code was restarting it, another Claude Code process stopped it, for example `claude stop` in another terminal. Claude Code keeps the session stopped:
2526
2527```text theme={null}
2528Session <id> was stopped while the respawn was in flight
2529```
2530
2531Opening a session you just dispatched, while its process is still starting, waits for the process instead. Before v2.1.246, opening it at that moment could stop it and show this message.
2532
2533**What to do:**
2534
2535* If you didn't stop the session, open its row again in agent view or run `claude respawn <id>` to restart it
2536* If you stopped it yourself, nothing remains to do: the session stays stopped
2537
2439<h3 id="session-agent-no-longer-available">2538<h3 id="session-agent-no-longer-available">
2440 Session agent no longer available2539 Session agent no longer available
2441</h3>2540</h3>
2482 2581
2483On some accounts the message says `daemon` in place of `background service`.2582On some accounts the message says `daemon` in place of `background service`.
2484 2583
2485Claude Code starts the background service through PowerShell so the service survives closing the terminal, using PowerShell 7 when it's installed and Windows PowerShell 5.1 otherwise. When neither PowerShell can run, Claude Code starts the service directly instead, so a policy that blocks only PowerShell doesn't cause this error. If you see it, the policy is blocking the Claude Code executable itself.2584On an npm installation, an `EUNKNOWN` that appears while `npm install -g @anthropic-ai/claude-code` is replacing the binary has the same cause as [`EACCES` during a reinstall](#eacces-when-starting-a-background-session) and clears when you retry after the install finishes.
2585
2586Claude Code starts the background service through PowerShell so the service survives closing the terminal, using PowerShell 7 when it's installed and Windows PowerShell 5.1 otherwise. When neither PowerShell can run, Claude Code starts the service directly instead, so a policy that blocks only PowerShell doesn't cause this error. If you see it while no npm install is running, the policy is blocking the Claude Code executable itself.
2486 2587
2487Before v2.1.212, Claude Code used only Windows PowerShell 5.1 to start the service, so any machine where Group Policy blocked PowerShell 5.1 failed with `Couldn't start the session — EUNKNOWN: unknown error, uv_spawn`, even with PowerShell 7 installed.2588Before v2.1.212, Claude Code used only Windows PowerShell 5.1 to start the service, so any machine where Group Policy blocked PowerShell 5.1 failed with `Couldn't start the session — EUNKNOWN: unknown error, uv_spawn`, even with PowerShell 7 installed.
2488 2589
2489**What to do:**2590**What to do:**
2490 2591
2491* If the message reads `Couldn't start the session`, upgrade to v2.1.212 or later. On earlier versions you can also run `claude daemon run` in a separate terminal first, then start the background session again. That command runs the background service in the terminal's foreground, so the service lasts only as long as that terminal stays open.2592* If the message reads `Couldn't start the session`, upgrade to v2.1.212 or later. On earlier versions you can also run `claude daemon run` in a separate terminal first, then start the background session again. That command runs the background service in the terminal's foreground, so the service lasts only as long as that terminal stays open.
2492* If the error appears on v2.1.212 or later, ask your Windows administrator to allow the Claude Code executable in the restriction policy2593* If an npm install was replacing the binary, wait for it to finish, then start the background session again
2594* If the error appears on v2.1.212 or later while no npm install is running, ask your Windows administrator to allow the Claude Code executable in the restriction policy
2493* If the background service stops when you close the terminal, Claude Code started it without PowerShell. Install PowerShell 7, or ask your administrator to unblock PowerShell, so the service can outlive the terminal.2595* If the background service stops when you close the terminal, Claude Code started it without PowerShell. Install PowerShell 7, or ask your administrator to unblock PowerShell, so the service can outlive the terminal.
2494 2596
2597### EACCES when starting a background session
2598
2599Claude Code couldn't run its own binary to start the [background service](/docs/en/agent-view#the-supervisor-process) that hosts background sessions. On an npm installation, this usually means `npm install -g @anthropic-ai/claude-code` was replacing the binary at that moment, whether you ran it or the [auto-updater](/docs/en/setup#auto-updates) did. The error appears when you open a session from [agent view](/docs/en/agent-view):
2600
2601```text theme={null}
2602Couldn't start the background service — spawn background service: EACCES: permission denied, posix_spawn '/usr/local/lib/node_modules/@anthropic-ai/claude-code/bin/claude'
2603```
2604
2605When you start a session with `/background` or `claude --bg`, the same reason appears inside `Couldn't reach the background service (...)`. During the same reinstall window the error can name another code instead, such as `ENOENT` or `ENOEXEC`, or `EUNKNOWN` or `EPERM` on Windows; an `EUNKNOWN` that persists across retries has a [different cause](#eunknown-when-starting-a-background-session).
2606
2607On an npm installation, Claude Code waits up to ten seconds for the reinstall to finish and retries on its own, so you see the error only when the binary stays unrunnable for longer, such as while npm is still downloading the package. Before v2.1.246, Claude Code failed at once.
2608
2609**What to do:**
2610
2611* Wait a few seconds, then open the session or dispatch again.
2612* If the error persists while no npm install is running, your user can't run the installed binary. Check its permissions and its directory's, or reinstall Claude Code.
2613
2614### Background service exited before it became reachable
2615
2616The process Claude Code started as the [background service](/docs/en/agent-view#the-supervisor-process) exited before it accepted connections, so Claude Code couldn't open your session. When the service printed an error before exiting, the reason in parentheses gives the exit code or signal and the first line the service printed, which names what stopped it:
2617
2618```text theme={null}
2619Couldn't reach the background service (background service exited before it became reachable (exit code N): <the service's first error line>) — run 'claude daemon status'
2620```
2621
2622When you open a session from [agent view](/docs/en/agent-view), the same reason follows `Couldn't start the background service —`. When the service printed nothing before exiting, the message says `nothing on stderr` instead.
2623
2624Claude Code reports the failure with the service's error line. Before v2.1.246, the failure surfaced only after a 45-second wait, as `background service did not become reachable within 45s`, without the service's error line.
2625
2626**What to do:**
2627
2628* If the message quotes a line, fix what it names, then open the session or dispatch again. The next attempt starts the service again
2629* Run `claude daemon status` to check whether a service is running now
2630
2495## Wrapper and IDE errors2631## Wrapper and IDE errors
2496 2632
2497These errors come from the program that launched Claude Code for you, such as an IDE extension or an [Agent SDK](/docs/en/agent-sdk/overview) application, rather than from Claude Code itself.2633These errors come from the program that launched Claude Code for you, such as an IDE extension or an [Agent SDK](/docs/en/agent-sdk/overview) application, rather than from Claude Code itself.
2616 2752
2617## Configuration warnings2753## Configuration warnings
2618 2754
2619Claude Code writes these messages to stderr rather than showing an error in the conversation, except where an entry notes that it writes the message to the debug log instead. It writes most of them at startup. Two exceptions: it writes the [unrecognized-model diagnostic line](#unrecognized-model-id-on-a-request) at request time, and the [unrecoverable interface error message](#exited-after-an-unrecoverable-interface-error) as it exits.2755Claude Code writes most of these messages to stderr, not into the conversation, and writes most of them at startup. An entry says so when its message appears somewhere else, such as in the debug log or as a startup notice in the conversation view, or at another time, such as the [unrecognized-model diagnostic line](#unrecognized-model-id-on-a-request) at request time.
2620 2756
2621<h3 id="fullscreen-failed-start-notice">2757<h3 id="fullscreen-failed-start-notice">
2622 Fullscreen renderer didn't finish starting2758 Fullscreen renderer didn't finish starting
2654 2790
2655Before v2.1.236, Claude Code exited without printing a message after this kind of error.2791Before v2.1.236, Claude Code exited without printing a message after this kind of error.
2656 2792
2793<h3 id="agent-descriptions-are-over-the-15000-token-limit">
2794 Agent descriptions are over the 15.0k-token limit
2795</h3>
2796
2797Claude Code shows this warning as a startup notice in the conversation view rather than on stderr. The combined descriptions of your [subagents](/docs/en/sub-agents), except the built-in ones, exceed 15,000 tokens as Claude Code estimates them. Each agent counts its name plus its `description` frontmatter. Claude Code loads every agent whether or not the total is over the limit, so the warning doesn't change what loads.
2798
2799```text theme={null}
2800Agent descriptions are over the 15.0k-token limit (~16.2k tokens) · ask Claude to trim agent descriptions in .claude/agents/
2801```
2802
2803**What to do:**
2804
2805* Shorten the `description` frontmatter of your agent files, or ask Claude to trim them for you.
2806* Remove agent files you no longer use.
2807
2657### Workspace has not been trusted2808### Workspace has not been trusted
2658 2809
2659Claude Code found `permissions.allow` rules or `permissions.additionalDirectories` entries in the project's `.claude/settings.json` or `.claude/settings.local.json` and didn't apply them, because [allow rules from project settings require workspace trust](/docs/en/permissions#project-allow-rules-and-workspace-trust). The count, the setting name, and the file named in the message vary with your configuration. `deny` and `ask` rules aren't affected.2810Claude Code found `permissions.allow` rules or `permissions.additionalDirectories` entries in the project's `.claude/settings.json` or `.claude/settings.local.json` and didn't apply them, because [allow rules from project settings require workspace trust](/docs/en/permissions#project-allow-rules-and-workspace-trust). The count, the setting name, and the file named in the message vary with your configuration. `deny` and `ask` rules aren't affected.
