# Claude Code Errors: What They Mean and How to Fix Them

> Most Claude Code errors are configuration rather than bugs. Here they are by family, with the two commands to run first and the real fixes.

URL: https://www.matthewswong.com/en/blog/claude-code-troubleshooting-common-errors/

- Author: Matthews Wong (https://www.matthewswong.com/en/about/)
- Published: 2026-08-27
- Updated: 2026-08-27
- Category: Software Development

> **Key takeaway:** Almost every Claude Code error falls into one of six families: authentication, usage limits, context, network, sessions, and tooling. Two commands identify which one you are in before you change anything — the diagnostics subcommand for installation and settings, and the status command for which credential, provider and proxy the session is actually using.

The most expensive hour I have lost to this tool was spent convinced my subscription had broken, when in fact an environment variable set months earlier for a different project was overriding it. The error said the API key was invalid. It was telling the exact truth, and I read it as a problem with my account because I had forgotten the key existed.

That is the shape of most trouble here: the message is accurate and the cause is somewhere you are not looking. This post groups the common failures by family — authentication, limits, context, network, sessions, and tooling — says what each one really means, and gives the fix rather than a suggestion to try again.

## Run these two before you change anything

Diagnose before you edit. The diagnostics subcommand prints installation and settings state, including which settings files are in play and how they resolved; the status command prints which credential, provider, base URL and proxy the running session is using. Between them they answer most questions outright, and turn the rest into a bug report someone can act on.

## Authentication: usually an environment variable

An API key in your environment overrides your subscription, silently and completely. That single fact explains most authentication confusion, including the case where someone is sure they are signed in and is nevertheless being billed as an API user. The messages are precise once you know what to look for.

> Do not fix an authentication error by adding another credential. If a key is being rejected, the correct move is to remove it and sign in, not to set a second variable in the hope that one of them works. Two credentials in play is how you end up with a session that authenticates differently from the one in the next terminal, which is much harder to diagnose than the original error.

## Limits, context, and the difference between them

These two families get confused constantly because both stop the work and both mention something being full. They are unrelated: a usage limit is about your plan and resets on a clock, while a context error is about this conversation and is fixed by shrinking it.

| Family | What it means, and what to do |
| --- | --- |
| Session or weekly limit reached | Your plan's quota, with a reset time. Wait, switch model, or add usage credits. Claude Code can wait in the open session and continue on its own |
| Credit balance too low | Different thing entirely — prepaid credits on a metered account. Add credits; there is no reset to wait for |
| Prompt is too long, compaction failed | The conversation exceeds the window and could not be summarised. Clear to start fresh, or compact with instructions to keep what matters |
| Context limit reached | The window is full and auto-compaction is not available. Clearing is the reliable fix; check what is filling it first |
| Model not recognised or restricted | A model name in config that does not exist, or one your organisation or plan does not allow. Open the model picker to see what is actually available |

## Network, TLS and timeouts

Corporate networks produce the errors that look most alarming and are usually the most mechanical. A certificate failure behind a proxy that re-signs traffic is not a security incident, it is a missing CA bundle. A request that times out on a slow link is a default that is too low for your network rather than a hung service.

> A response that stopped mid-stream is not lost work. Type continue and Claude resumes from the last completed block — that covers a dropped connection, a laptop that went to sleep, and a stream that simply stalled. People routinely re-ask the whole question instead, which pays for the same tokens twice and loses the partial output.

## Sessions that will not come back

Session errors are specific and each one means something different, which is worth knowing because only one of them is genuinely unrecoverable:

- A failure to resume the conversation means the transcript is corrupted or gone. That one is not recoverable — start a new session.
- No conversation found with that session ID means the ID is wrong, the session was cleaned up under your retention period, or a hand-copied duplicate made the lookup ambiguous.
- A session running an agent that is no longer available means the agent definition moved or was deleted. The session still resumes, with default tools and system prompt, and tells you which agent it could not find.

## Auto mode and tooling

Auto mode has its own error family because it involves a second model. When the classifier is rate-limited or overloaded, it says so and falls back to asking you after repeated failures. When the conversation is too large for the classifier, compaction fixes it. And when the classifier cannot parse its own result, it blocks the action rather than guessing — which is the correct trade, even though it reads like a malfunction.

MCP failures are usually simpler than they look. A server that fails to start appears in the plugin Errors tab, commonly with a missing executable, because a language server or tool binary has to be installed separately from the plugin that configures it. A subagent that would start with no tools at all is refused outright rather than being allowed to fail later.

## When it really is not you

Some failures are upstream, and the tell is that they arrive suddenly across everything you run rather than in one project. Repeated overloaded responses mean the service is at capacity, and a five hundred means a server-side failure. Check the status page before you go further, because the alternative is spending an hour bisecting a configuration that never changed.

> For CI, tune two variables deliberately. Lowering the retry count makes a pipeline fail fast instead of sitting through a long back-off, which is usually what you want when a human is not watching. Raising the request timeout is the opposite trade, and is right on a slow or heavily proxied network. Both defaults are chosen for an interactive session, not for a build agent.

Read the message literally, then check what the session is actually configured with rather than what you believe it is configured with — those two things disagree far more often than either the tool or the network is broken. Keep the diagnostics and status commands in muscle memory, keep the troubleshooting flags for when configuration is the suspect, and check the status page before assuming any of it is your fault.

## Sources & further reading

- Claude Code docs — Common errors
- Claude Code docs — Troubleshoot installation and login
- Claude Code docs — Enterprise network configuration
- Claude Code docs — Authentication
- Claude Code docs — Environment variables
- Claude Code docs — Costs and usage
- Claude Code docs — Context window
- Anthropic status page

## Source links

- https://code.claude.com/docs/en/errors
- https://code.claude.com/docs/en/troubleshoot-install
- https://code.claude.com/docs/en/network-config
- https://code.claude.com/docs/en/authentication
- https://code.claude.com/docs/en/env-vars
- https://code.claude.com/docs/en/costs
- https://code.claude.com/docs/en/context-window
- https://status.claude.com

## FAQ

### Why does Claude Code say my API key is invalid when I am signed in?

An API key in your environment overrides your subscription completely. If a stale or rejected key is set, Claude Code uses it instead of your login. Unset the variable and sign in again. The status command shows which credential the running session is actually using, so check that before changing anything else.

### What do I do when Claude Code says the prompt is too long?

The conversation exceeds the context window and automatic compaction could not reduce it. Start a fresh conversation, or run compaction with instructions about what to keep. Checking what is consuming the window first usually reveals a large file or tool output that does not need to stay in context.

### How do I fix an SSL certificate error in Claude Code?

This is almost always a corporate proxy that re-signs TLS traffic, not a security problem with Claude Code. Point the NODE_EXTRA_CA_CERTS environment variable at your organisation's CA bundle so the certificate chain validates. If you are behind a proxy at all, set HTTPS_PROXY as well.

### Can I recover a Claude Code session that fails to resume?

If the message is that resuming the conversation failed, the transcript is corrupted or deleted and that session cannot be recovered — start a new one. A message that no conversation was found with that session ID is different: the ID may be wrong, or the session may have passed your retention period.

### My Claude Code response stopped halfway. Do I have to ask again?

No. Type continue and Claude resumes from the last completed block. This covers a dropped connection, a computer that went to sleep, and a stalled stream. Re-asking the whole question pays for the same tokens twice and discards the partial output you already have.

---

- HTML version: https://www.matthewswong.com/en/blog/claude-code-troubleshooting-common-errors/
- Bahasa Indonesia: https://www.matthewswong.com/id/blog/claude-code-troubleshooting-common-errors/
- Site index for agents: https://www.matthewswong.com/llms.txt
- Sitemap: https://www.matthewswong.com/sitemap.xml
- API description (OpenAPI): https://www.matthewswong.com/openapi.json
