Skip to main content
BlogSoftware Development

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.

Matthews Wong

Software Engineer

August 202612 min read
Claude Code Errors: What They Mean and How to Fix Them

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.

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 disabled

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.

# "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:
/status

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.

What the message is actually telling you:

FamilyWhat it means, and what to do
Session or weekly limit reachedYour 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 lowDifferent thing entirely — prepaid credits on a metered account. Add credits; there is no reset to wait for
Prompt is too long, compaction failedThe conversation exceeds the window and could not be summarised. Clear to start fresh, or compact with instructions to keep what matters
Context limit reachedThe window is full and auto-compaction is not available. Clearing is the reliable fix; check what is filling it first
Model not recognised or restrictedA 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.

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

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.

FAQ

Frequently Asked Questions

Short answers to what readers ask most about this topic.

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.