Claude Code Troubleshooting: Common Errors and How to Fix Them

Claude Code is generally reliable, but when something does go wrong it’s rarely obvious from the error message alone. This guide covers the most common problems people run into — authentication errors, permission issues, MCP connection failures, and a few oddities that trip up new users — and exactly how to fix each one.

“Invalid API Key” or Authentication Errors

This is the most common issue, and it’s almost always one of three things:

• The key isn’t set correctly. Check your environment variable with echo $ANTHROPIC_API_KEY (Mac/Linux) or echo $env:ANTHROPIC_API_KEY (Windows PowerShell). If it’s empty, you’ll need to set it again and restart your terminal.
• The key has been revoked or expired. Generate a fresh one from the Anthropic Console and update it.
• You’re mixing up a Claude.ai account with an API account. Claude Code authenticates against your Anthropic API account, not a regular Claude.ai subscription — they’re billed and managed separately.

Claude Code Won’t Start / Command Not Found

If typing claude in your terminal does nothing or returns “command not found”:

• Confirm Node.js is installed with node --version — Claude Code requires a reasonably recent Node version.
• Reinstall with npm install -g @anthropic-ai/claude-code and check for errors during install.
• On Windows, make sure you’re using a terminal that’s been restarted since installation — PATH changes don’t apply to already-open windows.

Permission Errors When Editing Files

Claude Code asks for your approval before making significant changes, but if it’s failing outright rather than just asking:

• Check the file isn’t read-only or locked by another process (a running dev server, an open editor with unsaved changes, etc.).
• On Mac/Linux, confirm you have write permissions in the project directory — ls -la will show you.
• If you’re working inside a Docker container or restricted environment, Claude Code needs the same file permissions your shell user has.

MCP Server Connection Failures

If an MCP server you’ve configured isn’t responding:

• Check the server process is actually running — MCP servers that run locally (rather than as a hosted service) need to be started separately in most setups.
• Check the URL/port in your MCP configuration matches where the server is actually listening.
• For remote MCP servers over SSE, network issues (firewalls, VPNs) are a common cause — test the endpoint directly with curl before assuming Claude Code is the problem.

For a worked example of setting up a remote MCP server, see our Outlook MCP Server guide.

Claude Code Is Slow or Hangs

A few common causes:

• Large context. If Claude Code has read a lot of files into context, responses take longer. Starting a fresh session for a new task usually helps.
• Network issues. Since Claude Code calls the Anthropic API over the network, a slow or unstable connection shows up as slow responses.
• Rate limits. If you’re on a usage-based API plan and hitting rate limits, Claude Code will wait and retry — this can look like it’s hung when it’s actually just queued.

Changes Aren’t Being Applied

If Claude Code says it made a change but you don’t see it:

• Check you’re looking at the right file — Claude Code sometimes creates a new file rather than editing an existing one if the path wasn’t precise.
• Check your editor hasn’t cached an old version — some editors need a manual reload to pick up external file changes.
• Confirm you’re in the directory you think you’re in — pwd never lies, assumptions sometimes do.

Still Stuck?

If none of the above covers your situation, the two best places to check are the official Anthropic documentation and the Claude Code GitHub issues page, where most edge cases have already been reported and often resolved.

Related Guides

• What is Claude Code? The AI Coding Tool Explained
• How to Use Claude Code — Beginner’s Guide
• CLAUDE.md Explained