Troubleshooting guide for Claude Code, Codex and Cursor

Troubleshooting Claude Code, Codex and Cursor starts with finding which layer failed before retrying: the installation, login and billing, usage limits, configuration (instructions, permissions, MCP servers), the conversation’s context, or the output itself. Each tool ships a health check for the first layers, and a fix counts only when the repository’s own checks pass again.

This page is for developers who use one or more of these agents every day, and for the tech lead who fields “it stopped working” messages from a team. The agent stopped halfway through a refactor with an error you have never seen. Or it keeps ignoring the rule that is plainly in AGENTS.md, or a teammate’s session bills an old API key instead of the team plan. Retrying the same prompt harder fixes none of these, and it burns your allowance.

Tool-specific depth lives elsewhere: troubleshooting a Claude Code session, Codex error recovery, Cursor error handling, and MCP connection issues. This page is the cross-tool triage that tells you which of them you need.

What this troubleshooting guide gives you

• A six-layer triage table that names the failing layer in under two minutes
• The health-check commands for each tool, checked against Claude Code 2.1.283 (the latest channel) and codex-cli 0.157.1 on 2026-09-26
• Fixes for the failures that generate most support questions: command not found, the wrong credential, usage limits, ignored instructions, context drift, and lost work
• Three copy-paste prompts: triage before retrying, a clean hand-off to a fresh session, and proof that the recovery is sound
• A checklist for a bug report that maintainers can act on

Which layer broke? Triage before you retry

Match the symptom to a layer, run the first check, and stop at the first check that fails. Most wasted hours come from fixing a prompt when the problem was a credential, or reinstalling when the problem was context.

Layer	Typical symptom	First check
Installation	command not found, an old version, a feature from the changelog missing	claude --version / codex --version, then the health check below
Login and billing	Login loop, 401, usage billed to the wrong account	/status or claude auth status; codex login status
Limits and capacity	“usage limit reached”, 429, “overloaded”	/usage in Claude Code or Codex
Configuration	Rules in CLAUDE.md or AGENTS.md ignored, a permission rule that “doesn’t work”, MCP tools missing	/memory and /permissions (Claude Code); /debug-config (Codex); the Rules and MCP settings (Cursor)
Context	Repeats work, reopens decisions, forgets a constraint from an hour ago	/context (Claude Code); /status (Codex)
Output	A diff that is too big, off-task, or breaks the build	git diff --stat, then your test and type-check commands

Copy-paste prompt: triage before you retry

Stop. Do not edit any file in this turn. Help me find which layer is failing.
1. Configuration: list the instruction files (CLAUDE.md, AGENTS.md, rules) you
   loaded for this repository and any permission rule, hook or MCP server that
   affected your last action.
2. Context: state in three sentences what you believe the task is, which files
   matter, and which earlier decision from this conversation you are relying on.
3. Output: run `git diff --stat` and name the one change you are least sure of.
End with the single command I should run to confirm which layer it is.

Run the built-in health checks

Each CLI has a read-only health check. Run it before you edit a setting, and again after the fix.

Claude Code

# Terminal
claude --version       # latest and stable channels differ by about a week
claude doctor          # installation health and problems in the settings files
claude auth status     # which account and method are active

Inside a session, /doctor runs a fuller checkup that can also fix what it finds, and /status shows version, model, account, API connectivity, and tool status. To test whether your own customizations cause the problem, start once with claude --safe-mode, which disables CLAUDE.md, skills, plugins, hooks and MCP servers for that session.

Codex

# Terminal
codex --version
codex doctor           # installation, config, auth and runtime health
codex doctor --json    # redacted machine-readable report for a bug report
codex login status

Inside the TUI, /status shows the session configuration and token usage, and /debug-config shows the config layers and requirement sources, which is how you find the file that overrides yours. codex --strict-config makes Codex exit on keys in config.toml that this version does not recognize, instead of silently ignoring them.

Cursor

Cursor is a desktop editor, so its checks live in the UI rather than a doctor command. Open the MCP settings to see each server’s status, the Rules settings to see which rules apply, and Help > Toggle Developer Tools for the console errors behind a failed request.

cursor.com could not be reached when this page was checked on 2026-09-26, so confirm the current menu names in Cursor’s documentation. Every recovery step on this page also works with git alone.

Fix “command not found” after installing

A new install that the shell cannot find is almost always a PATH problem or two competing binaries.

Claude Code

1. Open a new terminal. The terminal you installed from still has the old PATH.
2. Check for duplicates: which -a claude must print exactly one path. Two paths usually mean an old npm install alongside the native one.
3. If ~/.local/bin/claude exists but is not found, add the directory to PATH in your shell profile:

   echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

4. Reinstall with the native installer, curl -fsSL https://claude.ai/install.sh | bash, and confirm with claude doctor.

Never use sudo npm install -g. On native Windows, Claude Code uses Git Bash when Git for Windows is installed and the PowerShell tool otherwise, so a missing Git no longer blocks the install. The Claude Code installation guide covers every install method and release channel.

Codex

1. Open a new terminal and run which -a codex. One path should print.
2. If you installed with npm and get EACCES, fix the npm prefix or use a Node version manager rather than sudo.
3. Reinstall with one method only: npm install -g @openai/codex, or brew install --cask codex on macOS.
4. Confirm with codex --version and codex doctor.

The Codex installation guide covers the install script and Windows.

Cursor

Cursor installs as a desktop app. If it will not start after an update, quit it completely and start it again with extensions disabled, then re-enable them one at a time to find the one that breaks startup. See Cursor installation and setup.

Fix login loops and usage billed to the wrong account

Most login problems are two credentials competing, not a broken login.

• Claude Code bills an API key instead of your plan. An exported ANTHROPIC_API_KEY can win over the subscription login. Run /status or claude auth status --text to see the active method, remove the variable from your shell profile, and run claude auth login. The Claude Code authentication guide lists the full precedence order.
• Codex uses a key you did not expect. codex login status reads the stored login in ~/.codex/auth.json; the auth row of codex doctor also names keys that come from the environment. Unset stale OPENAI_API_KEY or CODEX_API_KEY values before you sign in again.
• No browser on the machine (SSH, a container). Use codex login --device-auth for Codex. For Claude Code, see the SSH and CI sections of its authentication guide.
• A CI job fails at a login prompt. CI never uses a person’s session. Give the job an API key from the CI secret store, as the Codex authentication guide shows for codex exec.

Never paste a key into a command line or a prompt; read it from an environment variable or a secret manager.

Why did I hit a usage limit or an “overloaded” error?

Three different things produce “limit” messages, and each has a different fix.

Message	What it means	What to do
Plan usage limit reached	Claude Code and Codex subscriptions meter usage in rolling five-hour and weekly windows	Run /usage in either tool: Claude Code shows what is contributing to your limits, Codex shows account usage and any usage-limit reset you can apply
429 or rate limit on an API key	The API account’s own rate limit, separate from subscription windows	Slow parallel jobs down, or raise the tier in the provider console
“Overloaded” or 529	The provider is at capacity; nothing is wrong with your setup	Wait and retry once. In Claude Code, --fallback-model names a model to fall back to when the default is overloaded

The biggest self-inflicted drain is a retry loop: each retry re-sends the whole conversation. Before retrying a long session, run /compact or start fresh with the hand-off prompt below. Model choice and effort are covered on the models hub, and spending controls on Claude Code cost control and Codex cost management.

Why is the agent ignoring my instructions or permissions?

When the agent ignores a rule, first prove the rule loaded, then prove it applies to this action.

Claude Code

• /memory lists the CLAUDE.md files in play. Claude Code reads AGENTS.md only when a project has no CLAUDE.md (v2.1.277 and later, both release channels on 2026-10-12).
• /permissions shows each rule and the settings file it comes from. A deny rule in a file that is not loaded does nothing.
• If claude --safe-mode makes the problem disappear, the cause is one of your customizations; bisect them. The Claude Code troubleshooting page walks through the permission-rule traps.

Codex

• Since 0.150.0, an untrusted project does not supply project-level AGENTS.md. If Codex ignores the repository’s file, check whether you trusted the project.
• /debug-config shows which config layer set each value, including admin constraints from requirements.toml.
• /permissions shows what Codex may do. The Codex AGENTS.md guide covers file discovery and length.

Cursor

• Open the Rules settings and confirm the rule is listed and applies to the files in question.
• Keep rules short and specific. A rule the agent cannot check (“write clean code”) is not a rule.
• The Cursor project rules guide covers scoping.

A rule that must never be broken belongs in a hook, a permission rule or a CI gate, not only in prose. Permissions and sandboxing shows how to move a rule from “please” to “cannot”.

Why does the agent forget earlier decisions?

Long sessions degrade quietly. When the context fills, the tool compacts older turns into a summary, and a decision made an hour ago can drop out of it. The symptoms are repeated work, reopened decisions and ignored constraints.

Tool	See the usage	Summarize	Start clean
Claude Code	/context	/compact	/clear
Codex	/status	/compact	/new

In Cursor, start a new chat. In every tool, starting clean works better than compacting when the task changed, provided you carry the decisions across with the hand-off note below. Read context windows for how to keep sessions small from the start.

Copy-paste prompt: hand off to a fresh session

We are about to start a fresh session. Write a hand-off note to HANDOFF.md with:
1. The goal in one sentence and the acceptance check that proves it is done.
2. Every decision we made, each with its reason, including approaches we rejected.
3. Files changed so far (from `git diff --stat`) and the state of the tests.
4. The exact next step.
Do not include anything you are unsure about; mark open questions as OPEN.

Start the new session with “Read HANDOFF.md and continue from the next step.”

Fix an MCP server that will not connect

The three checks below find most causes. Run them in order.

1. Print the entry the client actually uses: claude mcp get <name>, codex mcp get <name> --json, or the block in .cursor/mcp.json.
2. Run the entry’s command and args in a terminal. If it exits with an error, the client fails the same way.
3. Check that every variable the server needs is set in the entry’s env, and that remote OAuth is complete (/mcp in Claude Code, codex mcp login <name> in Codex).

Timeouts, spawn ENOENT, 401s on remote servers, and the CLI flags that save a broken entry are covered in MCP connection issues.

Recover work an agent overwrote

Stop the agent first, so it does not keep “fixing” the damage. Then pick the smallest undo that covers it.

1. Press Esc to stop the current turn, and run git status and git diff --stat to see what changed.
2. Undo inside the tool when the damage is recent:
   • Claude Code: /rewind, or Esc twice, restores code, conversation or both to an earlier checkpoint.
   • Cursor: restore the checkpoint from before the response that broke things. Checkpoints cover one chat’s file edits (Cursor’s checkpoint page could not be re-checked on 2026-09-26).
   • Codex: 0.157.1 has no undo slash command, so git is the undo. /diff shows the working-tree changes, including untracked files.
3. Undo with git when the tool cannot: git restore <path> for one file, git stash to park everything, or git reset --hard <commit> to return to a known commit.
4. Recover a lost commit with git reflog. It records where HEAD pointed, so it rescues commits, not edits you never committed.
5. Undo side effects by hand. No checkpoint covers what the agent did through the terminal: an applied migration, an installed package, a pushed branch.

Prevention costs one command. Commit before any large agent task, or run the agent in its own worktree (claude --worktree, codex --worktree), so the undo is always git reset to that commit. The per-tool recovery pages go further: Claude Code error recovery, Codex error recovery, and Cursor error handling.

How do you prove the fix actually worked?

A fix is done when the evidence says so, not when the agent says so. You should not need to read every changed line to know.

1. Re-run the thing that failed. The same command, the same health check, the same MCP tool call. Green output replaces “it should work now”.
2. Run the repository’s gates. Tests, type check and lint, the same ones CI runs. A recovery that skips them has only moved the failure.
3. Check the scope. git diff --stat against the last good commit should show only the files the fix needed. Unexpected files are the next incident.
4. Record it. A one-line note in the pull request or the team channel: symptom, layer, fix, evidence. The developer who ran the fix signs off; the tech lead owns any change to shared settings files.

Copy-paste prompt: prove the recovery is sound

We just recovered from a broken change. Prove the working tree is sound, without editing files:
1. Run the test suite, the type check and the linter this repository uses
   (read package.json, Makefile or CI config to find them) and report pass or fail for each.
2. Run `git diff --stat` against the last commit on the main branch and list any file
   that the fix did not need to touch.
3. Re-run the command that originally failed and paste its output.
If anything fails, stop and report it. Do not fix it in this turn.

When the same failure keeps recurring, it is a harness problem, not a bad day. The failure taxonomy shows how to classify it and pick the control that catches it earlier.

What goes wrong while troubleshooting agents?

The fix can do more damage than the fault. These are the traps that show up most often.

Trap	Why it hurts	Do this instead
Retrying the same prompt in a loop	Each retry re-sends the whole context and drains the usage window	Triage first; compact or hand off before retrying
Silencing permission prompts with --dangerously-skip-permissions or --dangerously-bypass-approvals-and-sandbox	Removes the only guard between the agent and your machine	Add a specific allow rule; use full bypass only in a disposable, network-restricted sandbox
Deleting ~/.claude, ~/.codex or .cursor/ to “reset”	Loses settings, credentials, session history and MCP entries (for .cursor/: project rules and MCP config)	Use claude --safe-mode or codex doctor to isolate the cause; back up before deleting anything
Reinstalling with a second method	Leaves two binaries on PATH; the old one keeps winning	which -a, remove the extra one, keep one install method
Attaching raw debug logs to a public issue	Logs can contain paths, prompts and tokens	Use codex doctor --json (redacted) and read any log before you share it
Stale worktrees after a crashed parallel run	Branches stay locked and disk fills up	git worktree list, then git worktree prune

How do I report a bug maintainers can act on?

When the health check is green, the config is minimal, and the failure still reproduces, report it.

• Claude Code: /feedback or /bug sends a report from inside the session, or open an issue at anthropics/claude-code.
• Codex: /feedback sends logs to the maintainers, or open an issue at openai/codex.
• Cursor: report through the app or the Cursor forum.

Include the version, the operating system, the exact error text, the minimal steps to reproduce it (ideally with claude --safe-mode or a bare config.toml), and what you already ruled out with the triage table.

Where to go next after troubleshooting

• Troubleshoot a Claude Code session: permission rules, CLAUDE.md, over-built diffs
• Codex error recovery and Cursor error handling: undo and restart decisions per tool
• MCP connection issues: every MCP failure in detail
• Permissions and sandboxing: turn recurring “please don’t” into enforced rules
• Frequently asked questions: short answers on plans, models and setup