Top Claude Code Errors in 2026 and How to Fix Them

Most Claude Code problems fall into six families: it will not install, it will not sign in, it cannot reach the network, the API pushes back, you hit a usage limit, or the session gets slow. Each family has a short list of real error messages and a known fix. This guide collects the ones developers hit most, quoting the messages as the official documentation does, with the cause and the fix for each, plus a small script that checks your environment for the most common culprits.

Start here: five built-in diagnostics

Also useful: /context to see what fills the context window, and /feedback to report a problem directly from the session.

Find your error

1. Install and PATH errors

For a first install, the recommended route is the native installer (curl -fsSL https://claude.ai/install.sh | bash on macOS and Linux; Windows has its own PowerShell command in the official docs). It does not depend on a particular Node.js version. On WSL, make sure a Windows Node.js is not shadowing the Linux one on your PATH.

2. Login and credential errors

Credential problems account for a large share of confusing errors because several sources can supply a credential at once: a saved subscription login, environment variables, and helper scripts. Environment variables and apiKeyHelper take precedence over /login. When behavior surprises you, run /status first.

If you hit a revoked-key situation on the API side, see our page on a revoked Anthropic API key.

3. Network, proxy, and TLS errors

# Corporate proxy that re-signs TLS traffic
export HTTPS_PROXY=http://proxy.example.com:8080
export NODE_EXTRA_CA_CERTS=/path/to/company-ca.pem     # add both lines to your shell profile

# Stale key overriding your subscription login (macOS/Linux)
env | grep ANTHROPIC          # find it
unset ANTHROPIC_API_KEY       # then remove it from ~/.zshrc, ~/.bashrc, and any .env file
claude                        # relaunch, then run /status and /login if needed

Claude Code does not retry TLS certificate failures, so a certificate error never fixes itself. It also explains stalls on networks that buffer or interrupt streaming responses; the general method is in our guide to debugging streaming failures.

4. API errors

Our provider pages go deeper on the underlying API errors: Anthropic 529 overloaded and Anthropic 429 too many requests.

5. Usage limit and spend messages

These are not API failures. They mean your plan or spend allowance is used up, and retrying does nothing until it resets or you add capacity.

6. Interrupted responses

You may see The response above may be incomplete, or a variant such as Connection lost mid-response, Your computer went to sleep mid-response, or The response stream was malformed. The stream failed after Claude had already produced some text or a tool call. Claude Code keeps that output instead of silently re-running the request, which avoids repeating a tool call that already ran. In an interactive session, reply continue. In non-interactive mode, resume the session and send continue.

7. Context and performance problems

# Search tool, @file mentions, or custom skills finding nothing:
# install ripgrep with your package manager (brew, apt, apk, pacman, winget), then:
export USE_BUILTIN_RIPGREP=0          # or put it in the "env" block of settings.json
claude doctor                         # the Search line should show your system ripgrep path

The /heapdump command writes a heap snapshot for investigating memory use. That file contains every string in the process, including your whole conversation and credentials, so never attach it to a public issue. Attach only the smaller diagnostics file if you report a bug.

8. Retries and timeouts: the knobs that matter

Claude Code retries many failures on its own, so you rarely need your own wrapper for interactive use. For scripts and unattended jobs, these settings control the behavior:

CLAUDE_CODE_MAX_RETRIES=10          # default 10; lower it in scripts that should fail fast
CLAUDE_CODE_RETRY_WATCHDOG=1        # unattended or CI: keep retrying 429 and 529
API_TIMEOUT_MS=600000               # per-request timeout in ms (default is 10 minutes)
CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS=60000   # how long to wait for the first byte of a response

Claude Code does not retry TLS certificate failures, usage-policy denials, or output-filter blocks. For unattended work, also use an apiKeyHelper script to supply credentials instead of interactive login, and pass an explicit permission mode in non-interactive runs, since tool calls can be denied when a run does not specify one.

9. A script that checks the usual suspects

Many of the errors above come from the environment, not from Claude Code. This script checks for the most common causes: a stale or corrupted credential variable, a key that overrides your subscription, a malformed custom header, a proxy without a CA bundle, a bad timeout value, a missing claude or rg binary, and missing cloud-provider settings. It never prints credential values.

import os, shutil
from dataclasses import dataclass

SECRETS = ("ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN", "CLAUDE_CODE_OAUTH_TOKEN")


@dataclass
class Finding:
    level: str        # error | warn | info
    where: str
    message: str
    fix: str


def bad_header_chars(value: str) -> list:
    # HTTP headers cannot carry line breaks, NUL bytes, or characters above U+00FF.
    problems = []
    if "\r" in value or "\n" in value:
        problems.append("a line break")
    if "\x00" in value:
        problems.append("a NUL byte")
    if any(ord(c) > 0xFF for c in value):
        problems.append("a character above U+00FF (curly quote or zero-width space?)")
    return problems


def diagnose(env: dict, which=shutil.which, exists=os.path.exists) -> list:
    out = []

    def add(level, where, message, fix):
        out.append(Finding(level, where, message, fix))

    for name in SECRETS:                                  # never print the values themselves
        v = env.get(name)
        if v is None:
            continue
        probs = bad_header_chars(v)
        if probs:
            add("error", name, "contains " + " and ".join(probs),
                "Retype the value instead of pasting it again, then run /status.")
        elif v != v.strip():
            add("warn", name, "has leading or trailing whitespace", "Trim the value.")

    if env.get("ANTHROPIC_API_KEY"):
        add("warn", "ANTHROPIC_API_KEY",
            "is set, and environment keys take precedence over a saved /login",
            "On a Pro, Max, or Team plan, unset it (shell profile and .env files) unless you want "
            "API billing. Run /status to confirm the active credential.")

    for n, line in enumerate((env.get("ANTHROPIC_CUSTOM_HEADERS") or "").splitlines(), 1):
        if line.strip() and ":" not in line:
            add("error", "ANTHROPIC_CUSTOM_HEADERS", f"line {n} is not in 'Name: Value' form",
                "Use one 'Name: Value' pair per line.")
        elif "\x00" in line or any(ord(c) > 0xFF for c in line):
            add("error", "ANTHROPIC_CUSTOM_HEADERS", f"line {n} contains an invalid character",
                "Retype that header.")

    proxy, ca = env.get("HTTPS_PROXY") or env.get("https_proxy"), env.get("NODE_EXTRA_CA_CERTS")
    if ca and not exists(ca):
        add("error", "NODE_EXTRA_CA_CERTS", f"file not found: {ca}",
            "Point it at your company CA bundle (PEM file).")
    if proxy and not ca:
        add("info", "HTTPS_PROXY", "a proxy is set but NODE_EXTRA_CA_CERTS is not",
            "If the proxy inspects TLS and you see SELF_SIGNED_CERT_IN_CHAIN or similar errors, "
            "set NODE_EXTRA_CA_CERTS to your company CA bundle.")

    t = env.get("API_TIMEOUT_MS")
    if t is not None and (not t.isdigit() or int(t) <= 0):
        add("error", "API_TIMEOUT_MS", f"{t!r} is not a positive number of milliseconds",
            "Use a value such as 600000.")

    if not which("claude"):
        add("error", "PATH", "claude was not found on PATH",
            "Open a new terminal, or add the install directory to PATH, then run claude doctor.")
    if env.get("USE_BUILTIN_RIPGREP") == "0" and not which("rg"):
        add("error", "USE_BUILTIN_RIPGREP", "set to 0 but ripgrep (rg) is not installed",
            "Install ripgrep with your package manager, or remove the variable.")

    if env.get("CLAUDE_CODE_USE_BEDROCK") and not env.get("AWS_REGION"):
        add("warn", "CLAUDE_CODE_USE_BEDROCK", "AWS_REGION is not set",
            "Set AWS_REGION to a region where your model is enabled, and check aws sts get-caller-identity.")
    if env.get("CLAUDE_CODE_USE_VERTEX"):
        missing = [v for v in ("ANTHROPIC_VERTEX_PROJECT_ID", "CLOUD_ML_REGION") if not env.get(v)]
        if missing:
            add("warn", "CLAUDE_CODE_USE_VERTEX", "missing " + ", ".join(missing),
                "Set them, and run gcloud auth application-default login.")

    order = {"error": 0, "warn": 1, "info": 2}
    return sorted(out, key=lambda f: order[f.level])


if __name__ == "__main__":
    findings = diagnose(dict(os.environ))
    for f in findings:
        print(f"[{f.level.upper()}] {f.where}: {f.message}\n    fix: {f.fix}")
    if not findings:
        print("No common environment problems found. Run /doctor inside Claude Code next.")

And its tests, which run without Claude Code installed:

def run(env, have=("claude",), files=()):
    return diagnose(env, which=lambda n: "/usr/bin/" + n if n in have else None,
                    exists=lambda p: p in files)


def where(findings, name):
    return [f for f in findings if f.where == name]


def test_clean_environment_has_no_findings():
    assert run({}) == []


def test_pasted_key_with_a_line_break_is_an_error_and_never_echoed():
    f = run({"ANTHROPIC_API_KEY": "sk-ant-secret\nabc"})
    errs = [x for x in where(f, "ANTHROPIC_API_KEY") if x.level == "error"]
    assert errs and "line break" in errs[0].message
    assert all("secret" not in (x.message + x.fix) for x in f)


def test_curly_quote_and_zero_width_space_are_caught():
    assert any(x.level == "error" for x in run({"ANTHROPIC_AUTH_TOKEN": "tok​en"}))
    assert any(x.level == "error" for x in run({"CLAUDE_CODE_OAUTH_TOKEN": "“tok”"}))


def test_api_key_precedence_warning():
    f = run({"ANTHROPIC_API_KEY": "sk-ant-abc"})
    assert any(x.level == "warn" and "precedence" in x.message for x in f)


def test_custom_headers_format():
    f = run({"ANTHROPIC_CUSTOM_HEADERS": "X-One: 1\nbroken line\nX-Two: 2"})
    assert [x.message for x in where(f, "ANTHROPIC_CUSTOM_HEADERS")] == ["line 2 is not in 'Name: Value' form"]


def test_proxy_and_ca_bundle_checks():
    assert any(x.level == "info" for x in run({"HTTPS_PROXY": "http://p:8080"}))
    missing = run({"HTTPS_PROXY": "http://p:8080", "NODE_EXTRA_CA_CERTS": "/nope.pem"})
    assert where(missing, "NODE_EXTRA_CA_CERTS")[0].level == "error"
    ok = run({"HTTPS_PROXY": "http://p:8080", "NODE_EXTRA_CA_CERTS": "/ca.pem"}, files=("/ca.pem",))
    assert ok == []


def test_timeout_and_path_checks():
    assert where(run({"API_TIMEOUT_MS": "ten"}), "API_TIMEOUT_MS")
    assert where(run({"API_TIMEOUT_MS": "0"}), "API_TIMEOUT_MS")
    assert not where(run({"API_TIMEOUT_MS": "600000"}), "API_TIMEOUT_MS")
    assert where(run({}, have=()), "PATH")


def test_ripgrep_override_requires_ripgrep():
    assert where(run({"USE_BUILTIN_RIPGREP": "0"}), "USE_BUILTIN_RIPGREP")
    assert not where(run({"USE_BUILTIN_RIPGREP": "0"}, have=("claude", "rg")), "USE_BUILTIN_RIPGREP")


def test_cloud_provider_settings():
    assert where(run({"CLAUDE_CODE_USE_BEDROCK": "1"}), "CLAUDE_CODE_USE_BEDROCK")
    assert not where(run({"CLAUDE_CODE_USE_BEDROCK": "1", "AWS_REGION": "us-east-1"}), "CLAUDE_CODE_USE_BEDROCK")
    v = where(run({"CLAUDE_CODE_USE_VERTEX": "1", "CLOUD_ML_REGION": "us-east5"}), "CLAUDE_CODE_USE_VERTEX")
    assert "ANTHROPIC_VERTEX_PROJECT_ID" in v[0].message and "CLOUD_ML_REGION" not in v[0].message


def test_errors_sort_first():
    f = run({"HTTPS_PROXY": "http://p", "API_TIMEOUT_MS": "x"})
    assert [x.level for x in f] == ["error", "info"]

Preventing the common ones

• Keep one credential source. Decide between subscription login and API key, and remove the other from your profile and .env files.
• Retype, do not paste, secrets that came from documents or chat apps.
• Keep sessions focused. Compact early, give large files to subagents, and avoid dumping huge outputs into the conversation.
• Pin down your network. Document your proxy and CA bundle for the team, and test streaming through the proxy.
• Update regularly. Many reported problems are fixed in later versions, and the docs call out version-specific behavior.
• Check status before debugging. A 500 or 529 is often an incident, not your setup.

For the same errors from the raw API instead of the CLI, use the API error troubleshooting directory.

Sources

• Claude Code documentation: Error reference
• Claude Code documentation: Troubleshooting
• Claude Code documentation: Troubleshoot installation and login
• Claude Help Center: Troubleshoot Claude Code installation and authentication

Frequently asked questions

Keep reading