Error Codes Reference — Claude Cert Academy

Error Codes Reference

This page covers common Claude Code errors with their causes and fixes. Errors are grouped by origin: API, environment, MCP, permissions, and configuration.

API Errors

401 Unauthorized

• Cause: ANTHROPIC_API_KEY is not set, is empty, or the key has been revoked.
• Fix: Run echo $ANTHROPIC_API_KEY to verify the variable is set. If empty, add export ANTHROPIC_API_KEY=sk-ant-... to your shell profile (~/.zshrc or ~/.bashrc) and run source ~/.zshrc.
• Also check: the key has not expired or been rotated in the Anthropic console.

403 Forbidden (Bedrock)

• Cause: Using Claude Code via Amazon Bedrock but the specific Claude model has not been enabled in the AWS account.
• Fix: AWS Console > Amazon Bedrock > Foundation Models > find the Claude model > click Request Access. Wait for approval (usually immediate for most regions).
• Also check: the IAM role has bedrock:InvokeModel permission for the specific model ARN.

Environment Errors

claude: command not found

• Cause: Claude Code was installed but the install directory is not on the shell PATH.
• Fix: Restart the terminal. If still not found, find the install path with which claude or locate claude, then add its directory to PATH. Example: echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc.
• Common install paths: ~/.local/bin, /usr/local/bin, or wherever npm global packages install (npm prefix -g)/bin.

CLAUDE.md not loading

• Cause: On Linux (case-sensitive filesystem), the file is named claude.md, Claude.md, or CLAUDE.MD instead of exactly CLAUDE.md.
• Fix: Rename the file: mv claude.md CLAUDE.md (or whatever the wrong casing is). Verify with ls -la.
• Note: macOS is case-insensitive by default — the same file works on Mac and silently fails on Linux CI. Always use exact casing in version control.

Context window full at session start

• Cause: CLAUDE.md plus all @import files are too large and consume most of the context window before any conversation starts.
• Fix: Reduce CLAUDE.md size. Move rarely-needed content to separate files and only @import them conditionally. Keep CLAUDE.md under ~1500 lines and imported files under 500 lines each.
• Diagnosis: Run claude --debug and look for the context_tokens value reported at session start.

Auto-memory not saving

• Cause: Claude Code cannot write to the auto-memory directory (~/.claude/projects/).
• Fix: Check write permissions: ls -la ~/.claude/. If owned by root or another user, fix with sudo chown -R $USER ~/.claude/. Alternatively, check disk space with df -h.

MCP Errors

permission denied (MCP server)

• Cause: The MCP server binary is not executable.
• Fix: chmod +x /path/to/mcp-server. Verify with ls -la /path/to/mcp-server — should show -rwxr-xr-x or similar.

command not found (MCP server)

• Cause: The server binary is not on the PATH that Claude Code inherits at launch, even if it's on your interactive shell PATH.
• Fix: Use an absolute path in the command field of settings.json (e.g. /usr/local/bin/mcp-db-server instead of mcp-db-server). Alternatively, set PATH explicitly in the env field of the server config.

connection refused (MCP HTTP/SSE)

• Cause: The url in settings.json is wrong, or the remote MCP server is not running.
• Fix: Verify the URL is reachable: curl -v https://mcp.example.com/v1/health. Start the server before launching Claude Code if it's a local HTTP server.

auth failure (MCP HTTP/SSE)

• Cause: The token referenced in headers is missing or expired.
• Fix: Confirm the environment variable is set in the shell where Claude Code launches (not just in another terminal). Check expiration for OAuth tokens.

Permission Errors

Tool permission denied

• Cause: A deny rule in settings.json (project or global) is silently blocking the tool call.
• Fix: Run /config to open settings.json and inspect the permissions.deny array. Check both the project settings.json and ~/.claude/settings.json — both are active. Remove or scope the deny rule appropriately.
• Note: Denied tools fail silently from Claude's perspective — it sees a permission error, not a crash. Enable --debug to see which rule matched.

Continue to Claude Cert Academy