Claude Code Error Handling
Every Claude Code error has a root cause and a fix. This page organizes every documented error by type, links to step-by-step resolution guides, and teaches you a systematic diagnostic approach so you can fix new errors independently.
Bookmark this page. When Claude Code throws an error, start here.
API Errors (HTTP Status Codes)
API errors are the most common category. Each HTTP status code indicates a specific problem with your request, authentication, or the Anthropic service.
400 – Bad Request
The API rejected your request due to malformed input, invalid parameters, or schema violations.
- Fix: Claude API Error 400 InvalidRequestError – parameter validation failures and request formatting
401 – Authentication Error
Your API key is missing, expired, or malformed.
- Fix: Claude API Error 401 AuthenticationError – key rotation and environment variable troubleshooting
- Fix Claude API Error 401 – quick authentication repair steps
413 – Request Too Large
Your prompt or context exceeds the model’s input token limit.
- Fix: Claude API Error 413 RequestTooLarge – context window management and chunking strategies
429 – Rate Limit Exceeded
You have exceeded your API rate limit or token budget.
- Fix: Claude API Error 429 Rate Limit – rate limiting strategies and backoff patterns
- Claude API Error 429 rate_limit_error – detailed rate limit error analysis
- Fix Claude AI Rate Exceeded Error – practical rate management
500 – Internal Server Error
The Anthropic API encountered an internal failure.
- Fix: Anthropic API 500 Error – workarounds and retry strategies
- Fix Claude API Error 500 – server-side error recovery
- Fix Claude API Error 500 ApiError – understanding 500 error variants
529 – Overloaded
The API is temporarily overloaded and cannot process your request.
- Claude API 529 Overloaded Error – queuing and retry patterns during high load
SDK and Runtime Errors
These errors occur within the Anthropic SDK itself, usually during streaming, tool use, or structured output processing.
- Fix Anthropic SDK IndexError When Streaming – index out of range during stream processing
- Fix Anthropic API Streaming Interrupted – connection drops mid-stream
- Anthropic SDK Streaming Connection Dropped – network-level stream failures
- Fix Stream Idle Timeout in Claude Code – streams that hang without error
- Fix: SDK TypeError: terminated – abrupt SDK termination
- Anthropic SDK Python Async Context Manager Error – Python async/await SDK issues
- Anthropic SDK TypeScript Tool Results Type Mismatch – TypeScript type errors in tool results
- Fix: Anthropic SDK toolRunner Drops Headers – header propagation failures
- Fix: Anthropic SDK Grammar Too Large – structured output schema size limits
- Fix: Structured Output + Thinking + Tool Use Bug – interaction conflicts between features
JSON Parse Errors
JSON parsing failures occur when Claude Code receives malformed responses or when configuration files contain syntax errors.
- Fix Unexpected Token in JSON – malformed API response handling
- Fixing Claude Code’s ‘Unexpected End of Input’ – truncated JSON responses
- JSON Parse Error on Malformed Response – response corruption recovery
- Response JSON Parse Failure – systematic JSON debugging
- Config File JSON Parse Error – corrupted configuration files
- Claude Code Config YAML Parse Error – YAML syntax issues in config files
Permission and Access Errors
Permission errors block Claude Code from reading, writing, or executing in your project.
- Claude Code EACCES Permission Denied (npm) – npm global install permissions
- Fix Claude Code NPM Install EACCES – alternative npm permission fixes
- npm Global Install Permission Denied – system-level permission repair
- Claude Code Permission Denied Shell Commands – shell execution restrictions
- Claude Code Permission Denied Sandbox – sandbox mode conflicts
- EACCES Permission Denied Config Dir – configuration directory access
- XDG Config Directory Permissions – Linux XDG path permissions
- Claude Code Docker Permission Denied – Docker bind mount access issues
MCP Server Errors
MCP (Model Context Protocol) server errors occur during tool integration and external service communication.
- Fix: MCP Server Disconnected Error – server connection drops
- Fix Claude Code MCP Server Connection Closed – premature connection termination
- Claude Code MCP Server Connection Refused – server unreachable
- MCP Server stdio Timeout 30000ms – stdio transport timeouts
- Fix Claude Code MCP Timeout Settings – configuring timeout values
- Fix: Anthropic SDK MCP Tools Get Empty Arguments – tool argument passing failures
- Fix MCP Server Issues in Claude Code – incident response for MCP failures
Process and System Errors
These errors relate to Claude Code’s runtime process, system resources, or integration with your development environment.
- Claude Code EPIPE Broken Pipe Error – pipe failures during long operations
- Fix Claude Code Large File Crashes – memory exhaustion on large files
- Parallel Tool Calls Memory Exhaustion – out-of-memory during parallel execution
- Fix Claude Code Crashing in VS Code – VS Code extension host crashes
- VS Code Extension Host Crash Fix – extension host process recovery
- Fix Claude Code Bun Crash – Bun runtime crashes
- Fix Claude Code ‘Bun Has Crashed’ Error – Bun crash recovery steps
Diagnostic Approach
When you encounter an error not listed above, follow this systematic process:
- Read the error message carefully. Claude Code errors include specific codes and descriptions. The error code alone often points to the fix.
- Check your configuration. Most errors trace back to CLAUDE.md syntax, settings.json misconfigurations, or environment variable issues.
- Isolate the component. Determine whether the error originates from the CLI, the API, an MCP server, or your project code.
- Use the diagnostic tool. The Claude Code Diagnostic Tool walks you through error identification and resolution interactively.
- Check API status. For 500 and 529 errors, verify the Anthropic API status page before debugging your own configuration.
Frequently Asked Questions
What is the most common Claude Code error?
Error 429 (Rate Limit Exceeded) is the most frequently encountered error, especially for teams running multiple agents in parallel. The fix involves implementing exponential backoff, distributing requests across time windows, and optionally upgrading your API tier.
How do I fix Claude Code permission denied errors?
Permission denied errors have three common causes: npm global install permissions (fix with nvm or npm config), sandbox mode restrictions (check your permission mode setting), and file system permissions in Docker containers (fix bind mount ownership). Start with the Permission Denied Shell Commands guide.
Why does Claude Code crash on large files?
Claude Code loads file contents into the context window. Files exceeding the context limit cause crashes or truncation. Split large files, use .claudeignore to exclude generated files, and set max file size limits in your CLAUDE.md. See Fix Claude Code Large File Crashes.
How do I debug MCP server connection issues?
First, verify the MCP server process is running. Then check transport configuration (stdio vs HTTP). Next, test the connection independently using curl or the MCP inspector. Finally, review timeout settings. The MCP Server Incident Response Guide covers all steps.
What causes JSON parse errors in Claude Code?
Three sources: truncated API responses (network interruption), malformed configuration files (syntax errors in settings.json), and response schema mismatches (SDK version incompatibility). The fix depends on the source. See Fix Unexpected Token in JSON.
How do I handle Claude API 500 errors?
API 500 errors are server-side issues at Anthropic. Implement retry logic with exponential backoff (initial delay 1s, max 3 retries). If errors persist beyond 5 minutes, check the Anthropic status page. Your code is not the problem. See Fix Claude API Error 500.
Can I prevent errors before they happen?
Yes. Add error-prevention rules to your CLAUDE.md (file size limits, forbidden patterns, required validations). Use pre-commit hooks to validate Claude’s output before it commits. Enable the diagnostic tool for real-time error detection. See CLAUDE.md for Error Handling.
Where do I report Claude Code bugs?
Report bugs to the Anthropic Claude Code GitHub repository. Include your Claude Code version, the full error message, your operating system, and minimal reproduction steps. The Bug Reporting Best Practices guide shows how to write effective bug reports.
Explore More Guides
- Non-error issues and fixes
- Prevent errors with best practices
- Configuration-related error prevention
- Beginner guide to Claude Code
- Advanced debugging and monitoring
Stop Debugging, Start Building
This error reference covers the documented error types. For proactive error prevention patterns, debugging workflows, and production monitoring configurations, the Claude Code Mastery Playbook ($99) includes 200 production-tested practices that help you avoid errors entirely.