Software Development
Claude Code Errors: What They Mean and How to Fix Them
August 202612 min read
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.
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.
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.
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.
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.
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.
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.
claude doctor # installation + settings diagnostics
/status # which credential, provider, base URL and
# proxy this session is actually using
/usage # plan limits and reset times
/context # what is filling the context window
claude --debug # verbose, with an optional category filter
claude --version
# Two flags that remove variables when something misbehaves:
claude --bare # skip auto-discovery of hooks, skills,
# commands, subagents, plugins, MCP
claude --safe-mode # start with all customisations disabledAn 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.
# "Invalid API key · Fix external API key"
# An ANTHROPIC_API_KEY in your environment OVERRIDES your
# subscription. If you signed in and are still being billed
# as an API user, or a stale key is being rejected:
unset ANTHROPIC_API_KEY
/login
# "Could not resolve authentication method"
# A worker or background process has no credential. Export the
# variable in the environment, not just in an interactive shell.
# "Your organization has disabled API key authentication"
# Policy, not a bug. Use /login instead of a key.
# Check what is actually in force before changing anything:
/statusDo 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.
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.
What the message is actually telling you:
| 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 |
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.
# Timeouts and retries
API_TIMEOUT_MS=600000 # default 10 minutes
CLAUDE_CODE_MAX_RETRIES=10 # lower it for fast failure in CI
BASH_DEFAULT_TIMEOUT_MS=120000
BASH_MAX_TIMEOUT_MS=600000
# TLS through a corporate proxy that re-signs certificates:
export NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.crt
# Behind a proxy at all:
export HTTPS_PROXY=http://proxy.internal:8080
# A response that stopped mid-stream — a dropped connection, a
# laptop that slept — is not lost. Type:
continue
# and Claude resumes from the last completed block.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.
Session errors are specific and each one means something different, which is worth knowing because only one of them is genuinely unrecoverable:
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.
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