Debugging & Troubleshooting
Every Claude Code user hits a wall at some point — an auth error that blocks sign-in, a session that runs out of context, a tool that silently fails, or a rate limit that stops work mid-task. This lesson gives you a clear fix for each one.
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 below.
Something went wrong
Error message or unexpected output
Read the full error
The first line usually says exactly what failed
Identify the category
Auth? Context? Tool? Rate limit? Network?
Apply the specific fix
Use the section below for your error type
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
What you see
Error: Not authenticated. Please run 'claude auth login' to authenticate.
Why it happens
Your session has expired or you have never signed in on this machine.
How to fix it
- 1Run claude auth login in the terminal
- 2Complete the browser flow — a code is printed, paste it back
- 3Run claude --version to confirm the session is active
Invalid or expired API key
What you see
AuthenticationError: invalid_api_key — The provided API key is invalid.
Why it happens
The API key stored in your environment or .env file has been revoked, rotated, or mis-copied.
How to fix it
- 1Go to console.anthropic.com → API Keys and create a new key
- 2Update ANTHROPIC_API_KEY in your shell profile (~/.zshrc, ~/.bashrc) or .env file
- 3Restart the terminal and run claude auth status to verify
.env to .gitignore before your first commit.OAuth redirect fails (VS Code extension)
What you see
Sign-in window opens but redirects to an error page or just closes.
Why it happens
VS Code blocked the localhost redirect that the OAuth flow needs, or the browser intercepted it.
How to fix it
- 1Try signing in again — sometimes one retry is enough
- 2Disable any browser extensions that block redirects (uBlock, Privacy Badger)
- 3Use the Command Palette: "Claude Code: Sign Out", then sign in fresh
- 4If still failing, run claude auth login in the integrated terminal instead
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. Here is how it shows up and how to recover.
Fix 1 — Start a new conversation
Press Ctrl+N (requires enableNewConversationShortcut: true) or open a new Claude tab. Re-attach the relevant file with @filename and summarise the task briefly.
Fix 2 — Use /compact to summarise
Type /compact in the prompt box. Claude compresses the conversation history into a short summary and continues in the same session with more room.
Fix 3 — Use a CLAUDE.md to avoid re-explaining context
Anything that always needs to be true (stack, conventions, folder structure) should live in CLAUDE.md. It is loaded automatically in every new session — so you never lose that context when you start 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. Recognising tool failures early saves a lot of rework.
File read / write permission denied
What you see
ToolError: EACCES: permission denied, open '/path/to/file.ts'
Why it happens
Claude tried to read or write a file your system user does not have permission to access.
How to fix it
- 1Check who owns the file: ls -la /path/to/file.ts
- 2Fix ownership: sudo chown $USER /path/to/file.ts
- 3Or fix permissions: chmod 644 /path/to/file.ts
- 4Retry the same request — no need to repeat the prompt
Bash command not found
What you see
bash: npm: command not found (or node, python, git, etc.)
Why it happens
The tool Claude tried to call is not installed, or not on the PATH that Claude inherits in its shell.
How to fix it
- 1Install the missing tool (e.g. nvm install node, brew install python)
- 2Check your PATH: echo $PATH in the integrated terminal
- 3If using nvm/pyenv, ensure it is initialised in your shell profile before Claude runs
- 4Restart VS Code to pick up the updated PATH
Claude skips the tool silently
What you see
Claude describes the change but does not actually edit the file — and does not say why.
Why it happens
Claude was in Plan mode, or the file was not explicitly mentioned so it was not allowed to write.
How to fix it
- 1Check which permission mode is active (bottom of the prompt box)
- 2Switch to Default mode and ask again
- 3Add @filename to the prompt so Claude knows it has permission to touch that file
- 4If in Plan mode, approve the plan — Claude will then apply the edits
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 if you hit it |
|---|---|---|
| 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
Run through this before spending time investigating a tricky error.
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
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.