Claude Code Not Working? 12 Fixes That Actually Help

How to diagnose Claude Code problems before trying random fixes

Claude Code fails in distinct ways. Authentication failures look different from rate limit errors. Context degradation looks different from a permissions block. Trying fixes at random wastes time and can make some problems worse (clearing context when the real issue is a bad CLAUDE.md rule, for example, costs you the session state without fixing anything).

The fastest path to a working session is to identify the failure category first, then apply the specific fix for that category. This guide covers 12 of the most common Claude Code problems, grouped by type, with the specific command or configuration change that resolves each one. If your problem is a specific error message rather than general misbehaviour, fixing Claude Code errors fast maps individual errors to fixes, and if claude never installed cleanly in the first place, Claude Code installation failed is the place to start.

Before diving into specific fixes, run two diagnostic commands that cover the most common causes:

# Check authentication status
claude auth status

# Check current config including model and context usage
claude config list

If auth status reports an expired or missing token, fix that first. Everything else depends on a working auth session.

Authentication and account problems

Fix 1: Re-authenticate when the token expires

Claude Code API tokens expire. The symptom is Claude returning an authentication error mid-session or failing to start with a 401 Unauthorized response.

# Log out and back in
claude auth logout
claude auth login

# Verify the session is active
claude auth status

If you are using an Anthropic Console API key directly (rather than OAuth login), the key may have been rotated or revoked. Check the Console at console.anthropic.com under API Keys. If the key has been rotated, update the environment variable:

# In your shell profile (.zshrc, .bashrc, etc.)
export ANTHROPIC_API_KEY=sk-ant-your-new-key-here

# Reload the profile
source ~/.zshrc

# Confirm it is set
echo $ANTHROPIC_API_KEY

Claude Code reads ANTHROPIC_API_KEY from the environment. If the value in the environment does not match a valid active key, every request fails with an auth error regardless of what the claude auth command shows.

Fix 2: Check for rate limit errors vs auth errors

Rate limit errors and auth errors produce similar-looking failures. The difference matters because the fixes are different. A rate limit error will resolve on its own; an auth error will not.

Rate limit errors return HTTP 429. Auth errors return HTTP 401 or 403. The Claude Code CLI usually surfaces the HTTP status code in the error message. If you see 429, the fix is to wait and retry (or upgrade your plan). If you see 401 or 403, re-authenticate.

If you are hitting rate limits frequently:

# Check which model you are using (different models have different rate limits)
claude config get model

# Switch to a model with higher rate limits for your plan
claude config set model claude-sonnet-4-5

Rate limits on the Anthropic API are per-model and per-plan. If you are on the free tier using Opus and hitting limits, switching to Sonnet gives substantially higher throughput at lower cost. The rate limits for each plan are listed in the Anthropic Console under your account settings.

Context and memory problems

Fix 3: Clear a degraded context with /compact

When a long session produces incoherent or contradictory outputs, the context window is usually the culprit. Claude is working from a compressed or partial view of the conversation history.

The /compact command triggers a manual compaction: Claude summarises the conversation so far and continues from that summary, freeing up context space.

/compact

Before running /compact, write a brief summary of the current state to disk so the resumed session has accurate recovery context:

# Write a session state file before compacting
cat > /tmp/session-state.md << 'EOF'
# Session state before compact
- Task: Adding rate limiting to the auth service
- Completed: JWT middleware, token rotation endpoint
- Current file: src/middleware/rate-limit.ts
- Architecture decision: using redis-based rate limiting, not in-memory
- Next: implement the Redis connection in src/lib/redis.ts
EOF

Then run /compact and immediately read the state file back:

/compact

Read /tmp/session-state.md to restore context before continuing.

For a complete treatment of context management techniques including CLAUDE.md anchors and session handoffs, see Claude Code context management.

Fix 4: Start a fresh session for new tasks

Claude Code sessions carry forward the context of everything that happened earlier. This is useful within a task but becomes a liability when you start a genuinely different task. The earlier context pollutes Claude's assumptions about the new task.

When switching to a new, unrelated task:

# Start a fresh Claude Code session (opens a new instance)
claude

Or exit the current session and restart:

# In the current session
exit

# Then start fresh
claude

A fresh session reads CLAUDE.md but has no conversational history. This is the correct starting point for a new feature, a different codebase area, or a task that should not be influenced by the previous session's decisions.

Fix 5: Fix CLAUDE.md rules that are producing wrong output

If Claude Code consistently generates code in a style you do not want (wrong framework, wrong error handling pattern, wrong import style), the most common cause is either a missing rule in CLAUDE.md or a conflicting rule that Claude is resolving the wrong way.

Diagnose by asking Claude directly:

What rules from CLAUDE.md are you applying to this file?

Claude will surface which rules it is applying, making it possible to identify the gap or conflict. Then update CLAUDE.md:

# Open CLAUDE.md in your editor
code CLAUDE.md

# Or directly from a Claude Code session
# Ask Claude to update it
Please add a rule to CLAUDE.md: all async functions must return explicit types,
never use inferred return types on async functions.

Rules in CLAUDE.md are read at session start and held in context throughout. Updating CLAUDE.md takes effect in the next session. If you need the rule to take effect immediately in the current session, state it explicitly in the conversation:

New rule for this session: all async functions must return explicit types.
Apply this to every file you generate or modify.

File and edit problems

Fix 6: Claude is editing the wrong file

Claude Code sometimes edits a file in a different location than intended, particularly in monorepos with multiple packages or projects with similar directory structures.

The fix is explicit file path specification:

Edit the file at apps/web/src/components/Button.tsx
NOT packages/ui/src/Button.tsx
The web app has its own copy that extends the UI package version.

For projects where file path ambiguity is a persistent problem, add a directory map to CLAUDE.md:

## Directory map (resolve ambiguity with this)
- apps/web/src/        - Next.js app, user-facing frontend
- apps/admin/src/      - Next.js app, internal admin panel
- packages/ui/src/     - Shared component library (do NOT modify unless intent is to update the shared lib)
- packages/api/src/    - Shared API types and utilities
- packages/db/src/     - Drizzle schema and migrations (shared)

When editing a component, confirm which app it belongs to before editing.

Claude reads the directory map and uses it to resolve "which Button.tsx?" questions before making edits.

Fix 7: Claude is reverting changes you already made

If Claude overwrites changes you made in a previous message, it has lost track of the current state of the file. This happens when:

1. You made changes outside the Claude Code session (in your editor)
2. The session ran long enough that the earlier file state was summarised out of context
3. Claude misremembered the file state after generating multiple versions

The fix is to give Claude the current file content explicitly before asking for further edits:

Here is the current state of src/services/auth.service.ts:
[paste the file content]

Do not regenerate the entire file. Only add the rotateToken() method
after the existing refreshToken() method.

This grounds Claude's edits in the actual current file rather than its potentially stale memory of an earlier version.

Fix 8: Edits are failing with a file not found error

Claude Code resolves file paths relative to the working directory it was started from. If Claude was started from the project root but generates an edit for src/components/Button.tsx and the file is at a different path, the edit fails.

Verify the working directory:

# In the Claude Code session
pwd

If Claude was started from the wrong directory, exit and restart from the correct project root:

cd /path/to/your/project
claude

For monorepos, always start Claude Code from the root of the specific package you are working on, not from the monorepo root, unless you intend Claude to work across packages.

Tool and permission problems

Fix 9: Fix permission denied errors on Bash tools

Claude Code runs Bash commands with the same permissions as your user account. Permission denied errors usually mean either the target file is owned by a different user (common in Docker-generated files) or a .claude/settings.json deny rule is blocking the command.

Check the settings first:

cat .claude/settings.json

Look for a permissions.deny array. If the command Claude is trying to run matches a pattern in the deny list, that is the block:

{
  "permissions": {
    "deny": [
      "Bash(rm -rf*)",
      "Bash(git push*)"
    ]
  }
}

To allow a specific command, add it to the allow list:

{
  "permissions": {
    "allow": [
      "Bash(pnpm build*)",
      "Bash(pnpm test*)"
    ],
    "deny": [
      "Bash(rm -rf*)",
      "Bash(git push*)"
    ]
  }
}

For file permission errors (not settings-based), fix the underlying file permissions:

# If Docker created files owned by root
sudo chown -R $(whoami) ./node_modules
sudo chown -R $(whoami) ./dist

# Or fix a specific file
chmod 644 src/generated/types.ts

Fix 10: MCP tools are not appearing or not working

If a Claude Code MCP server is configured but its tools are not showing up in the session, the server failed to start. Common causes: missing environment variables, wrong binary path, or a dependency that is not installed. For the full diagnostic order on this specific problem, see Claude Code MCP not connecting.

Check the MCP configuration:

# List configured MCP servers
claude mcp list

# Check a specific server's status
claude mcp status server-name

For a server that is not connecting, check its configuration in .claude/mcp.json:

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["/absolute/path/to/server/index.js"],
      "env": {
        "API_KEY": "${MY_API_KEY}"
      }
    }
  }
}

Common fixes:

1. Use absolute paths in the command field. Relative paths fail because Claude Code may not be running from the same working directory as the terminal where you configured the server.

2. Ensure environment variables are set. The ${MY_API_KEY} syntax reads from the environment. If MY_API_KEY is not set, the server starts with an empty API key and will fail on its first tool call.

3. Test the server independently. Run node /absolute/path/to/server/index.js directly in a terminal to see its startup output and any errors. Claude Code hides server stderr by default.

4. Restart Claude Code after changing MCP configuration. MCP servers are started at session init. Changes to .claude/mcp.json require a full restart to take effect.

Performance and response quality problems

Fix 11: Responses are slow or timing out

Slow Claude Code responses are usually caused by one of three things: network latency to the Anthropic API, a model that is under high load, or a very long context that takes time to process.

Diagnose by checking:

# Check Anthropic API status
curl -s https://status.anthropic.com/api/v2/status.json | python3 -m json.tool

# Or visit https://status.anthropic.com

If the API status shows degraded performance, the only fix is to wait. Anthropic posts status updates when there are incidents.

If the API is healthy and responses are consistently slow, try switching to a faster model:

# Haiku is the fastest model in the Claude family
claude config set model claude-haiku-4-5

Haiku is appropriate for straightforward code generation, file edits, and conversational exchanges. Use Sonnet or Opus for complex multi-file reasoning, architecture decisions, and tasks that require synthesising large amounts of context.

For timeouts specifically, the default Claude Code timeout is fairly generous. If you are timing out on very long operations (generating a large file, processing many files at once), break the task into smaller chunks:

Instead of: "Refactor all 20 service files to use the new error handling pattern"

Use:
"Refactor src/services/user.service.ts to use AppError from src/lib/errors.ts.
Show me the result and wait for my confirmation before moving to the next file."

Smaller, sequential tasks with confirmation steps are more reliable than large batch operations and easier to review before they write to disk.

Fix 12: Output quality dropped significantly mid-session

Sudden quality drops within a session (not gradual degradation) usually indicate one of two things: the context window has been compacted and important context was lost in the summary, or a conflicting instruction was introduced mid-session that is overriding an earlier one.

For compaction-related drops, run a context refresh:

Context refresh:
- Project: TypeScript API with Fastify 4
- Current task: adding the payments module
- Files modified so far this session: src/routes/payments.ts, src/services/payments.service.ts
- Architecture rule: use AppError from src/lib/errors.ts, never throw raw errors
- Next step: add the webhook handler at src/routes/webhooks.ts

A 10-line context refresh costs very few tokens and immediately improves output quality if the drop was caused by context loss.

For instruction conflicts, ask Claude to surface its understanding of the current rules:

What rules are you currently applying for error handling in this project?

If the answer contradicts what CLAUDE.md says, there is a conflicting instruction somewhere in the conversational history. State the correct rule explicitly:

Correction: all errors must use AppError from src/lib/errors.ts.
The raw throw you generated earlier was wrong. Apply this rule to everything from here.

Systematic troubleshooting checklist

When Claude Code stops working correctly, work through this list in order before trying more disruptive fixes:

1. Auth: Run claude auth status. Fix auth before anything else.
2. Rate limit: Check if errors include HTTP 429. If so, wait 60 seconds and retry.
3. CLAUDE.md: Ask Claude what rules it is applying. Look for gaps or conflicts.
4. File paths: Confirm Claude is operating on the correct files with explicit paths.
5. Context health: Look for signs of degradation (contradictions, forgotten constraints). Run a context refresh.
6. Permissions: Check .claude/settings.json deny list if Claude cannot run a specific command.
7. MCP servers: Run claude mcp list and check for servers that failed to start.
8. Model: Switch to a different model if the current one is slow or hitting rate limits.
9. Fresh session: If nothing else works, start a fresh session and restore context from CLAUDE.md + a handoff file.

Most Claude Code problems resolve at steps 1 through 5. Steps 6 through 9 cover less common but specific failure modes. Reaching step 9 (fresh session) is a last resort because it costs the conversational context. The patterns in Claude Code context management are designed to make step 9 cheap by keeping a good handoff always available.

Get Claudify. CLAUDE.md templates, permission configs, and session management patterns that keep Claude Code working correctly across real development workflows.