Claude Code Troubleshooting: 10 Errors and Fixes (2026)

Jump to: quick triage · reverts changes · context compaction · edits outside scope · permission denials · conflicts with architecture · TypeScript errors pile up · monorepo confusion · token limits · Claude Code and Cursor together · hard-to-audit changes · common misunderstandings · FAQ

Start Here: Is It Claude Code, Your Setup, or the API?

Before treating anything below as one of the 10 behavior problems, rule out the three causes that look similar but aren't about how Claude Code behaves during a task.

If what you're actually dealing with is command not found: claude, a login loop, or a message about hitting a subscription or spend limit, that's an installation, login or usage-limit problem rather than one of the 10 below; those have their own fix paths in Anthropic's documentation. Everything from here on assumes Claude Code starts, you're signed in, and the API is reachable.

Error 1 - Claude Code Reverts Changes It Just Made

What you see: you ask Claude Code to build on a change from a few prompts ago, and it's gone, or back to an earlier version, with nothing having visibly failed.

Why it happens

Each new prompt gets Claude Code's own fresh read of the current files, not a memory of what it decided earlier in the conversation. If a file changed through something other than Claude Code's own edit, or an earlier plan was abandoned partway through, the next prompt can "correct" the file back toward whatever it expects, undoing work you wanted kept.

How to fix it

1. Commit after any change you want to keep, before asking for the next feature. A real git commit, not just a save, gives you an instant diff or revert point.
2. Keep each prompt scoped to the current step. "Continue from where you left off" invites Claude Code to reinterpret the state; naming the specific file and function doesn't.
3. Put hard constraints in the repo-root CLAUDE.md. It's the file Claude Code reads at session start; a subdirectory's CLAUDE.md only loads on demand, when Claude Code reads another file in that subdirectory, so a rule you can't afford to lose belongs at the root.

What you should see: the next prompt builds on the committed state, and git diff shows only what you asked for.

Error 2 - Context Compaction Fires Mid-Feature

What you see: partway through a multi-step task, Claude Code forgets a constraint you set earlier, or you see Autocompact is thrashing: the context refilled to the limit repeated in the error text

Why it happens

Claude Code automatically compacts (summarizes) the conversation once the context window fills up, and a summary can drop a specific detail that was never written down anywhere else. The thrashing message is a distinct case: compaction succeeds, but a file or tool output immediately refills the window several times in a row, so Claude Code stops retrying rather than burn API calls on a loop that isn't converging.

How to fix it

1. Keep anything you can't afford to lose in CLAUDE.md (conventions, the current task's constraints), not only in the conversation.
2. Run /compact proactively with a focus, for example /compact keep only the plan and the diff, instead of waiting for it to trigger on its own.
3. If you hit the thrashing message specifically, ask Claude Code to read the oversized file in smaller chunks (a line range or a single function) instead of the whole file, or move that piece of work to a subagent so it runs in its own context window.
4. Run /context to see what's actually loaded. If Messages is the largest row, a tool output is refilling the window; if everything else is larger, trim what loads at session start.

What you should see: /context shows headroom again, and the constraint you set earlier still holds in the next response.

Error 3 - Claude Code Modifies Files Outside the Requested Scope

What you see: you ask for a change to one file or component, and the diff touches files you never mentioned.

Why it happens

A broad or feature-level prompt reads as permission to touch anything related to it. "Update the checkout flow" can be taken as license to edit every file that flow imports, not just the one you had in mind.

How to fix it

1. Name the exact file or files in the prompt instead of describing the feature in general terms.
2. Ask Claude Code to list which files it plans to touch before it makes the change, and approve that list first.
3. List off-limits directories explicitly, either in the prompt or in CLAUDE.md (for example, "don't touch anything under /app/legacy").

What you should see: the diff is limited to the files you named.

Error 4 - Permission Denials Breaking the Workflow

What you see: Claude Code stops on a permission prompt, or the same action keeps getting blocked even after you thought you'd approved it.

Why it happens

Permission settings merge across scopes, and the closer one wins: local overrides project, which overrides user. Managed settings from an organization apply first and can't be overridden from any of the other scopes. A rule you set in one file can be silently overridden by another scope without an obvious error.

How to fix it

1. Run /status to see which settings sources are active, including whether managed settings are in effect.
2. If Claude Code can't reach a folder it needs, use --add-dir to grant access explicitly, rather than approving the same prompt repeatedly.
3. Remember that a Bash deny rule matches the literal command string, not the underlying executable: a rule blocking Bash(rm *) won't stop /bin/rm or a different way of invoking deletion. For a hard guarantee rather than a permission rule, use a PreToolUse hook or the sandbox.

What you should see: /status confirms the setting you expect is the one in effect, and the action runs, or stays blocked, only where you intended.

Error 5 - Generated Code Conflicts with Existing Architecture

What you see: new code duplicates a utility that already exists, or ignores the pattern the rest of the codebase follows.

Why it happens

Without being told your project's conventions, Claude Code writes in whatever pattern is most common for the language or framework, which isn't necessarily yours.

How to fix it

1. Document conventions in CLAUDE.md: naming, where utilities live, which libraries are already in use. This is exactly the kind of guidance CLAUDE.md is meant to hold, the same way you'd brief a new teammate on project conventions and where files belong.
2. Before generating something new, ask Claude Code to search for an existing implementation first.
3. Review the diff for duplicated logic before merging, not after.

What you should see: new code reuses existing utilities and matches the surrounding style.

Error 6 - TypeScript Errors Accumulate Across Sessions

What you see: small type errors pile up across several sessions until a build finally fails with a long list at once.

Why it happens

A session can look clean within the files it touched while a type change elsewhere breaks a caller that session never opened.

How to fix it

1. Run your type checker at the end of every session, not only before a deploy.
2. Ask Claude Code to fix type errors as a dedicated pass, pointing it at the checker's output directly, rather than folding the cleanup into unrelated feature work.
3. Keep the check in CI so a session can't silently ship a type error.

What you should see: the type checker runs clean at the end of each session.

Error 7 - Claude Code Gets Confused by Monorepo Structure

What you see: Claude Code edits the wrong package, or applies a rule that only one package follows to all of them.

Why it happens

Subdirectory CLAUDE.md files load on demand, when Claude Code reads another file in that subdirectory, rather than at session start. If a session never points Claude Code at a file inside a given package, that package's CLAUDE.md never loads, and Claude Code falls back to the repo-root file or to general conventions instead.

How to fix it

1. State the target package by path in the prompt every time, rather than assuming Claude Code remembers which one you're working in.
2. Keep a short structure map in the repo-root CLAUDE.md (which folder is which package), since that file always loads at session start.
3. If you need a package's own CLAUDE.md to apply, ask Claude Code to read one file inside that package first so the subdirectory file loads before the real task begins.

What you should see: edits land only in the named package, and package-specific rules apply only there.

Error 8 - Token Limits Hit on Large Codebases

What you see: a session on a large codebase slows down, hits a context-window error, or Claude Code's own memory usage climbs.

Why it happens

There's a hard limit on how much the model can hold in context at once, and reading whole large files eats into it quickly.

How to fix it

1. Narrow the scope: ask about a specific function or line range instead of an entire large file.
2. Split large tasks into smaller ones so each session's context stays manageable.
3. If a session's heap memory passes roughly 2.5GB, Claude Code shows a critical memory warning. Restart and run claude --continue to resume the same conversation in a fresh process.
4. If memory stays high after restarting, run /heapdump. It writes a heap snapshot and a diagnostics file to your desktop (your home directory on Linux, if there's no Desktop folder). The snapshot contains your full conversation and credentials, so don't attach it to a public issue; share only the -diagnostics.json file if you're reporting it.

What you should see: /context shows headroom, and repeat sessions on the same codebase stop climbing in memory.

Error 9 - Claude Code and Cursor Running on the Same Project

What you see: two AI coding tools editing the same files produce conflicting changes, or one tool's edit gets silently overwritten by the other.

Why it happens

Neither tool knows the other is active; each assumes its own pending changes are the only ones.

How to fix it

1. Commit, or at least stage, before switching tools, so each one starts from a clean, known state.
2. Assign ownership per task or per file, not per session: decide which tool is doing a given piece of work before you start it.
3. Diff after switching tools, not only at the end of the day.

What you should see: each tool's changes land on top of a clean, committed base, with no silent overwrites. If Cursor itself is the one acting up, see the Cursor troubleshooting guide.

Error 10 - Autonomous Changes That Are Hard to Audit or Revert

What you see: after a long agentic session, the diff is large enough that it's hard to tell what changed or why, and reverting means losing everything since the last commit.

Why it happens

Letting Claude Code run many steps unsupervised produces one large diff instead of a trail of small, reviewable ones.

How to fix it

1. Commit after each meaningful step, not only at the end of the session. Every commit is a point you can return to.
2. Keep sessions focused on one feature or fix so the resulting diff stays reviewable.
3. For a single session where you want fewer autonomous side effects to review, scope prompts tightly or start it with claude --safe-mode if plugins or hooks are adding unreviewed behavior of their own.

What you should see: git log shows a trail of small, named commits instead of one large, unreviewable diff.

Common Misunderstandings About Claude Code

• Claude Code doesn't notice a file you changed outside it in the same session unless you ask it to re-read that file. Editing in your IDE while a task is mid-flight can leave Claude Code working from a stale view.
• "Stuck thinking" isn't always frozen. Long reasoning or a large tool call before the first token appears can look identical to a hang, especially right after compaction; give it a minute before assuming it's stuck.
• --safe-mode disables your customizations for that one session only. It doesn't delete CLAUDE.md, plugins, hooks or MCP configuration; they're back in your next normal session.
• A 529 or 429 error isn't a sign that your account or your own usage is the problem. 529 specifically means capacity across all users, and doesn't count against your usage limit.

When It Isn't a Bug

• Claude Code deliberately withholds certain changes without your confirmation, such as destructive commands or broad deletions. That's the permission system working as designed, not a malfunction.
• Being prompted to switch models under high load ("please use /model to switch to Sonnet") is the system protecting overall response time, not an error in your setup.
• A Markdown table with more than 200 rows shows only the first 200 in the terminal by design. The full table stays in the conversation; ask Claude Code to write it to a file if you need the rest.

What to Include When You Ask for Help

• The exact error text, not a paraphrase. 529 and 429 look similar but mean different things.
• The output of claude --version and your operating system.
• Whether the problem still happens under claude --safe-mode, which rules out a plugin, hook or MCP server as the cause.
• The relevant part of claude doctor or /doctor output.
• If it's memory-related, the -diagnostics.json file from /heapdump, never the raw heap snapshot, since that one holds your conversation and credentials.

FAQ

Sources

• Debug your configuration - Anthropic, consulted 2026-10-15
• Troubleshooting - Anthropic, consulted 2026-10-15
• Error reference - Anthropic, consulted 2026-10-15
• status.claude.com - Anthropic's live status page
• AppStuck's Claude Code page for what else can go wrong once Claude Code is working correctly
• Claude Code MCP not working if the problem is specifically an MCP server