Debugging & Troubleshooting
Every Claude Code user hits a wall at some point — an auth error, a session that runs out of context, a tool that fails, or a rate limit mid-task. Each problem has a clear fix below.
When something goes wrong
Most errors fall into five categories. Read the error message, identify which category it belongs to, then jump to the right section.
| Step | What to do |
|---|---|
| 1. Read the full error | The first line usually says exactly what failed. |
| 2. Identify the category | Auth, context, tool, rate limit, or other. |
| 3. Apply the specific fix | Use the section below for your error type. |
| 4. Verify and continue | Re-run the same task — most errors clear immediately. |
Authentication errors
Auth errors prevent Claude Code from starting or making requests. They look alarming but almost always have a fast fix.
Not authenticated / login required
Error: Not authenticated. Please run 'claude auth login' to authenticate.
Why: Your session has expired or you have never signed in on this machine.
- Run
claude auth loginin the terminal. - Complete the browser flow — paste the code back when prompted.
- Run
claude --versionto confirm.
Invalid or expired API key
AuthenticationError: invalid_api_key — The provided API key is invalid.
- Go to console.anthropic.com → API Keys and create a new key.
- Update
ANTHROPIC_API_KEYin your shell profile or .env file. - Restart the terminal and run
claude auth status.
.env to .gitignore before your first commit.OAuth redirect fails (VS Code extension)
Sign-in window opens but redirects to an error page or just closes.
- Try signing in again — sometimes one retry is enough.
- Disable browser extensions that block redirects (uBlock, Privacy Badger).
- Use Command Palette: “Claude Code: Sign Out”, then sign in fresh.
- If still failing, run
claude auth loginin the integrated terminal.
Context overflow
Every conversation has a context window — a limit on how much text Claude can hold in memory at once. Long sessions eventually hit this limit.
| Fix | How |
|---|---|
| Start a new conversation | Press Ctrl+N (with enableNewConversationShortcut: true) or open a new Claude tab. Re-attach the relevant file with @filename and summarise the task. |
| Use /compact | Type /compact in the prompt box. Claude compresses history into a short summary and continues with more room. |
| Use CLAUDE.md | Put stack, conventions, and folder structure in CLAUDE.md so you never lose that context when starting fresh. |
Tool failures
Claude Code uses tools to read files, run commands, and write code. When a tool fails, Claude either reports an error or silently falls back to guessing.
| Error | Cause | Fix |
|---|---|---|
| EACCES: permission denied | Claude tried to access a file your user cannot read or write. | Check ownership with ls -la, then chown or chmod. Retry the same request. |
| bash: npm: command not found | The tool is not installed or not on PATH in Claude's shell. | Install the tool, verify PATH with echo $PATH, restart VS Code. |
| Claude describes the change but does not edit | Plan mode is active, or the file was not mentioned. | Switch to Default mode, add @filename, or approve the plan first. |
Rate limits
Rate limits are temporary pauses — not permanent errors. Claude Code tells you exactly how long to wait.
| Plan | Default limit | What to do |
|---|---|---|
| Free | Low (shared pool) | Wait the cooldown — usually under 60 s |
| Pro / Team | Higher per-minute quota | Wait a few seconds; most limits reset quickly |
| API key | Set on your console | Increase limits at console.anthropic.com |
Other common issues
| Problem | Quick fix |
|---|---|
| Claude edits the wrong file | Always include @filename in your prompt. Do not rely on Claude inferring the right file. |
| Claude installed a package you didn't want | Rewind to the checkpoint before that message, then re-prompt with the exact package name. |
| The VS Code extension panel won't open | Run "Developer: Reload Window" from the Command Palette, then try again. |
| Claude loops or repeats itself | Use /compact to clear the context, or start a fresh session with a precise single-task prompt. |
| claude command not found in terminal | The extension bundles the CLI but it may not be on PATH. Run: which claude. If missing, install via npm i -g @anthropic-ai/claude-code. |
| Network error / ECONNREFUSED | Check your internet connection. If behind a proxy, set HTTPS_PROXY in your environment. |
| TypeScript errors after Claude edits | Ask Claude: 'Fix TypeScript errors in @filename' — share the exact error from the Problems panel. |
Quick diagnosis checklist
| Check | Detail |
|---|---|
| Read the full error message | The first sentence usually contains the fix |
| Check authentication | claude auth status — takes 2 seconds |
| Check the permission mode | Default for most tasks; not Plan or Auto-accept by mistake |
| Verify the file was mentioned | @filename prevents almost all wrong-file edits |
| Look at context length | Long session? Run /compact or start fresh |
| Check installed tools | which node, which npm, which git — confirm they're on PATH |
| Rewind if something broke | Hover a message → rewind code — undo without losing history |
Before you continue
- Read the full error first — the first line usually points to the fix.
- Auth errors clear with
claude auth login. - Context overflow: run /compact or start fresh with @filename and CLAUDE.md.
- Tool failures often mean a missing binary or wrong permission mode.
- Next: writing and running tests with Claude Code.
What's Next
You've built a real app end-to-end with Claude Code. The next lesson goes deeper on testing — how to write, run, and iterate on tests for any project.