Troubleshooting

Diagnose common Claude Code issues

Use the /debug skill effectively

Read and interpret error messages

Fix authentication, permission, and connectivity problems

Know where to get help when stuck

Things break. Claude might not respond as expected, commands might fail, or the tool might not start at all. Knowing how to diagnose and fix issues saves time and frustration.

This lesson covers common problems and their solutions. Keep this as a reference for when things go wrong.

Problem: "API key not found" or similar auth errors

Claude Code needs valid API credentials.

Check your key:

If empty, set it:

Verify the key works:

If you get an error, the key may be invalid or expired.

Re-authenticate:

This walks through authentication again.

Check key permissions:

Some API keys have restricted permissions. Ensure yours has access to the models you are using.

Problem: "Network error" or timeouts

Check internet connectivity:

If this fails, you have a network issue.

Proxy configuration:

If behind a corporate proxy:

Firewall issues:

Ensure outbound HTTPS to api.anthropic.com is allowed.

VPN interference:

Some VPNs block or slow API calls. Try disconnecting temporarily.

Retry:

Transient network issues resolve themselves. Wait and retry.

Problem: Claude seems stuck or unresponsive

Check if Claude is thinking:

Complex tasks take time. Watch for the thinking indicator.

Cancel and retry:

Press Escape to cancel the current operation, then retry.

Reduce task complexity:

Break large tasks into smaller steps:

Check rate limits:

If you have been making many requests, you may hit rate limits. Wait a minute and retry.

Restart Claude:

A fresh session can resolve stuck states.

Problem: "Permission denied" or action blocked

Check permission mode:

See what mode you are in and what rules exist.

Check deny rules:

A deny rule may be blocking the action:

Remove or modify if it is blocking legitimate work.

Try default mode:

If auto mode is blocking too much:

Claude will ask before acting.

File system permissions:

If Claude cannot read or write files:

Check you have the necessary Unix permissions.

Problem: A tool fails with an error

Read the error message:

Claude shows error output. Look for specific messages.

Common Bash errors:

"command not found" - The tool is not installed

"permission denied" - File permissions issue

"no such file" - Path is wrong

Fix the underlying issue:

If npm is not found, install Node.js. If a file is missing, check the path.

Ask Claude for help:

Claude can often diagnose tool failures.

Problem: Claude forgets or seems confused

Context overflow:

Long sessions fill the context window. Claude may lose earlier details.

Summarize and reduce context, then continue.

Start fresh:

For unrelated tasks, start a new session rather than continuing in a cluttered one.

Provide context:

If Claude seems to have forgotten something:

Remind Claude of relevant context.

For complex issues, use the debug skill:

The skill:

Enables detailed logging

Analyzes session debug logs

Looks for patterns in errors

Suggests fixes

Read debug logs directly:

Look for error patterns.

Problem: Settings not applying

Check settings location:

User: ~/.claude/settings.json

Project: ./.claude/settings.json

Validate JSON:

If jq reports an error, your JSON is malformed.

Restart after changes:

Some settings require restarting Claude Code:

Check precedence:

User settings can override project settings. Make sure the right scope is set.

Problem: MCP server not connecting

Check the command exists:

If this fails, the package may not exist or npm is not working.

Check configuration:

Verify the JSON is valid.

Environment variables:

Ensure required env vars (API keys, tokens) are set correctly.

Restart Claude:

MCP servers are loaded at startup. Restart after config changes.

Problem: Claude is very slow

Check model:

Opus is slower than Sonnet, which is slower than Haiku.

Switch to a faster model if appropriate.

Reduce context:

Smaller context is faster to process.

Narrow scope:

Check network:

Slow connections make everything slower.

Official documentation:

https://code.claude.com/docs/en/

Known issues:

https://code.claude.com/docs/en/troubleshooting

Community:

Check forums, Discord, or GitHub issues for similar problems.

Ask Claude:

Claude can often help troubleshoot its own issues.

Support:

For account or billing issues, contact Anthropic support.

"Context length exceeded"

Your conversation is too long. Run /compact or start a new session.

"Rate limit exceeded"

Too many requests. Wait 60 seconds and retry.

"Model not found"

Invalid model name. Check available models with /model.

"Invalid API key"

Your key is wrong or expired. Re-authenticate with claude auth login.

"Tool not allowed"

A permission rule is blocking the tool. Check /permissions.

Authentication issues: Check API key, re-authenticate if needed

Connection issues: Check network, proxy, firewall

Permission issues: Check /permissions, adjust rules or mode

Context issues: Use /compact, start fresh sessions

Use /debug for complex troubleshooting

Read error messages carefully - they often indicate the fix

Restart Claude Code after configuration changes

Check documentation and community for known issues

Practice troubleshooting:

Run /cost to verify Claude is working.

Run /permissions to see your current rules.

Try to trigger an error: ask Claude to delete a critical file and see how it handles denial.

Run /compact to see context reduction in action.

Check if you have MCP configured: look at .claude/mcp.json if it exists.

Try /debug I want to understand how debugging works to see the debug skill in action.

Review your settings: cat ~/.claude/settings.json | jq .

This exercise familiarizes you with diagnostic tools.

https://code.claude.com/docs/en/troubleshooting - Official troubleshooting guide

https://code.claude.com/docs/en/debug - Debug skill documentation

https://code.claude.com/docs/en/faq - Frequently asked questions