# Troubleshooting guide for Claude Code, Codex and Cursor

URL: https://developertoolkit.ai/en/resources/troubleshooting/
Description: Find which layer broke in Claude Code, Codex or Cursor: install, login, usage limits, ignored rules, context drift, MCP or lost work. Then prove the fix.

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](/en/claude-code/operate/troubleshooting/), [Codex error recovery](/en/codex/quick-start/error-recovery/), [Cursor error handling](/en/cursor-ide/quick-start/error-handling/), and [MCP connection issues](/en/ecosystem/mcp/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**

```text
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**

```bash
# 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**

```bash
# 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](https://cursor.com/docs). 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:
   ```bash
   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](/en/claude-code/quick-start/installation/) 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](/en/codex/quick-start/installation/) 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](/en/cursor-ide/quick-start/installation-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](/en/claude-code/quick-start/authentication/) 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](/en/codex/quick-start/authentication/) 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](/en/ecosystem/models/), and spending controls on [Claude Code cost control](/en/claude-code/operate/cost-control/) and [Codex cost management](/en/codex/operate/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](/en/claude-code/operate/troubleshooting/) 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](/en/codex/quick-start/agents-md/) 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](/en/cursor-ide/quick-start/project-rules/) 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](/en/workflows/harness/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](/en/workflows/context/context-windows/) for how to keep sessions small from the start.

**Copy-paste prompt: hand off to a fresh session**

```text
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](/en/ecosystem/mcp/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](/en/claude-code/quick-start/error-recovery/), [Codex error recovery](/en/codex/quick-start/error-recovery/), and [Cursor error handling](/en/cursor-ide/quick-start/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**

```text
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](/en/workflows/operate/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](https://github.com/anthropics/claude-code/issues).
- **Codex:** `/feedback` sends logs to the maintainers, or open an issue at [openai/codex](https://github.com/openai/codex/issues).
- **Cursor:** report through the app or the [Cursor forum](https://forum.cursor.com).

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](/en/claude-code/operate/troubleshooting/): permission rules, `CLAUDE.md`, over-built diffs
- [Codex error recovery](/en/codex/quick-start/error-recovery/) and [Cursor error handling](/en/cursor-ide/quick-start/error-handling/): undo and restart decisions per tool
- [MCP connection issues](/en/ecosystem/mcp/mcp-connection-issues/): every MCP failure in detail
- [Permissions and sandboxing](/en/workflows/harness/permissions-and-sandboxing/): turn recurring "please don't" into enforced rules
- [Frequently asked questions](/en/resources/faq/): short answers on plans, models and setup