Debugging and Error Recovery

Error recovery in Cursor means undoing an agent change that broke the build or behaviour, then redoing the work under tighter constraints. Checkpoints roll back the agent’s file edits inside one chat, git commits protect everything between chats, and the recovery is accepted only when the build, tests, and a scoped diff agree, not on the agent’s word.

Documentation freshness

Covers: the Cursor 3.x line; the current release on 2026-10-12 is Cursor 3.24 (2026-10-09, Cursor’s release notes). Cursor’s agent overview says checkpoints “are stored locally and separate from Git” and that “Restoring a checkpoint reverts files only”, and the docs name the run modes Auto-review, Allowlist and Run Everything (all checked 2026-10-12). Plan Mode was first verified against cursor.com on 28 August 2026. Every recovery step below also works with git alone.

This page is for a developer who has built a first feature with Cursor’s agent and has now watched it go wrong. The agent refactored your authentication module, moved functions between files, and added a validation layer. The tests pass, but the login page renders blank in the browser. You ask it to fix that, it edits six more files, and now two tests fail that passed an hour ago.

What you get from a recovery routine in Cursor

• A two-layer undo setup (checkpoints plus git) that you put in place before the agent starts
• A decision table for when to restore a checkpoint, when to reset to a commit, and when to fix forward
• Four copy-paste prompts: the fresh-chat diagnosis, the scoped fix, runtime instrumentation, and the pre-PR gate
• The git commands that measure what the agent changed without reading the whole diff
• Recovery steps for the six ways recovery itself goes wrong

Why agent-made breakage needs a different recovery

Agent mistakes rarely look like typos. They look like finished work.

Typical human bug	Typical agent bug
Typo or off-by-one error	Code that compiles and type-checks but does the wrong thing
Forgotten edge case	A confident wrong assumption about a requirement
Copy-paste slip	A pattern from one part of the codebase applied where it does not fit
One broken function	Edits spread across many files, some of them unrelated to the task

Two consequences shape everything below. First, a passing build proves little, so you need evidence from behaviour: a test that reproduces the bug, or runtime logs. Second, the agent’s own account of what it changed is not reliable, so you measure the change with git instead of reading the chat.

Set up two undo layers before the agent starts

Cursor keeps checkpoints of the agent’s file edits within a chat, so you can go back to the state before a given response. They are stored locally and separate from git, and restoring one reverts files only (Cursor’s agent overview, checked 2026-10-12). Git is the layer that survives a closed chat, a restarted editor, and a teammate’s machine. Use both.

1. Start every agent task from a clean tree on its own branch. In a terminal:

   git status --short            # must print nothing; commit or stash first
   git switch -c fix/login-blank-page

2. Commit at every milestone the agent finishes, not only at the end. For a feature built in phases, that means one commit after the schema, one after the API, and one after the UI:

   git add -A && git commit -m "wip: API endpoints pass their tests"

3. Before a risky prompt (a refactor, a dependency upgrade, a migration), commit again. The commit, not the checkpoint, is your restore point if the editor closes or the chat is lost.

4. Know what a checkpoint cannot undo. Anything the agent did through the terminal is outside the file snapshot: a migration applied to your local database, a package installed, a file generated by a script. Treat those as not covered and undo them by hand.

Whether the agent asks you before each terminal command depends on the run mode you set under Settings > Agents > Approvals & Execution: Auto-review, Allowlist or Run Everything. Allow your test, lint, and build commands to run without a prompt rather than lifting approval for every command. See essential configuration for the setup.

Should you restore a checkpoint, reset to a commit, or fix forward?

Pick the smallest undo that removes the damage.

Situation	Undo with	Why
The last agent response made things worse, and earlier responses were fine	Restore the checkpoint from before that response	Removes one step and keeps the rest of the session’s work
Several responses in a row went wrong, or you cannot tell which one broke it	Keep a copy: git stash push -u -m "agent attempt" (this also cleans the tree). Discard: git restore --staged --worktree . back to your last commit, then git clean -nd to list files the agent created and git clean -fd to delete them	The commit is a known-good state; the checkpoint trail may not be
The chat is gone, Cursor restarted, or the change was already committed	git reset --hard LAST_GOOD_COMMIT on your branch, then git clean -nd and git clean -fd for files the agent created. If you already pushed, run git revert AGENT_COMMIT instead. LAST_GOOD_COMMIT and AGENT_COMMIT are hashes from git log --oneline	Only git has the history at this point
One piece is wrong and the rest is correct and tested	Fix forward with a scoped prompt (below)	Redoing good work costs more than fixing one part
The prompt itself was wrong or incomplete	Reset (and git clean -fd), then start a new chat with a better prompt	Fixing forward keeps building on a wrong premise

Caution

git restore --staged --worktree . and git reset --hard discard uncommitted changes without asking, and neither removes new untracked files; git clean -fd does, so preview it with git clean -nd. Run git stash push -u -m "before reset" first if there is anything in git status you might want back.

Stop an agent that loops on the same error

The pattern: the agent changes something, the test fails, it tries another approach, fails again, and starts repeating itself or undoing its own earlier fix. More prompts in the same chat rarely help, because the context now holds several failed approaches that pull the next attempt toward them.

1. Stop the agent from the chat so it does not keep editing.

2. Restore the checkpoint from before the loop started, or run git restore --staged --worktree . to go back to your last commit, then git clean -nd to list files the agent created and git clean -fd to delete them.

3. Find the cause yourself, or with the agent in Plan Mode, which plans before writing any code. Read the failing test’s actual output, not the agent’s summary of it.

4. Open a new chat and hand the agent the diagnosis, the file, and what it must not touch.

Copy-paste prompt: fresh-chat diagnosis after a loop

@src/auth/session.ts @tests/auth/session.test.ts

The test "redirects to /dashboard after login" fails with:
  TypeError: Cannot read properties of undefined (reading 'userId')
at src/auth/session.ts in getSessionUser.

Cause: the session middleware expects req.session to be populated,
but the test's request mock never sets it up. The production code is correct.

Fix the mock in tests/auth/session.test.ts so it creates req.session the way
src/middleware/session.ts does. Do not modify any file under src/.
Run `npx vitest run tests/auth/session.test.ts` and show me the output.
Stop after one attempt if it still fails and tell me what you observed.

The last line matters. An agent told to stop after one failed attempt reports back instead of starting a new loop.

Rein in an agent that changed too many files

You asked for a retry around one payment call and the agent also reformatted the billing module, renamed a helper, and touched three tests. Measure it first:

git diff --stat              # files and line counts changed since the last commit

If the list holds files the task never needed, restore the checkpoint and constrain the scope in the prompt itself. Name the file, name the helper to reuse, and say what is off limits.

Copy-paste prompt: a scoped fix in one file

Only modify src/services/billing.ts. Do not change any other file,
including tests, config, or formatting outside the function you edit.

Add retries to processPayment for network errors and HTTP 5xx responses only.
Use the existing withRetry helper in src/utils/retry.ts with 3 attempts and
exponential backoff. Do not retry 4xx responses.

When you are done, run `git diff --stat` and confirm that billing.ts is the only
file listed. Then run `npx vitest run src/services` and show me the result.

If the agent makes the same unwanted change in every session, the fix belongs in a project rule, not in each prompt.

When the tests pass but the feature is broken

Static reading does not find this class of bug. The agent needs runtime evidence: what the code actually did, in order, on the failing path. Ask for temporary, tagged logging at each step, reproduce the bug yourself, and paste the output back. Cursor’s help describes Debug mode as for tricky bugs that need runtime evidence (checked 2026-10-12); in any other mode the steps are the same.

Copy-paste prompt: runtime instrumentation for a browser-only bug

The login form works in tests but renders a blank page in the browser after
a successful POST /api/login (200, session cookie set).

Do not fix anything yet. Add temporary logging, each line prefixed with
[DEBUG-LOGIN], at these points:
- the submit handler in src/components/LoginForm.tsx (before and after the fetch)
- the redirect logic in src/auth/redirect.ts
- the first render of src/pages/dashboard.tsx

Tell me the exact steps to reproduce. I will paste the browser console
output back to you. After the fix, remove every [DEBUG-LOGIN] line.

The tag makes cleanup checkable: git grep -n --untracked "DEBUG-LOGIN" must print nothing before you commit. For intermittent failures, race conditions, and regressions that need git bisect, follow the full workflow in AI-assisted debugging in Cursor.

Prove the recovery without reading every line

“All tests pass” from the agent is a claim. Accept the recovery on evidence that you can check in a minute, in this order.

1. The gate is green. Build, lint, type check, and tests run to completion in the terminal, not in the agent’s summary.

2. The scope is what you asked for. git diff --stat main...HEAD lists only the files the task needed.

3. The tests were not weakened. git diff main...HEAD -- '*.test.*' '*.spec.*' shows no deleted assertions, no new .skip, and no loosened expected values. An agent under pressure to turn a test green sometimes edits the test instead of the code; see protect the oracle.

4. The debug code is gone. git grep -n --untracked "DEBUG-" prints nothing.

5. The original symptom is gone. Reproduce the bug the way you first saw it, or better, keep the failing test that reproduced it.

To make the gate automatic, run the test command and the DEBUG- grep from a Cursor stop hook that sends the agent back when either fails; see make Cursor re-run the gate. The agent can run the rest for you in one pass before you open the pull request.

Copy-paste prompt: pre-PR gate after a recovery

Run our full check: npm run build && npm run lint && npx tsc --noEmit && npm test

If anything fails, fix the code, not the tests, and rerun.
Stop after two failed attempts and report what you observed.
Stop and ask me if a fix would require changing a test's expected values.

Then compare this branch with main and report:
1. The output of `git diff --stat main...HEAD`, and any file you did not need to change
2. Any change under tests/ or in *.test.* / *.spec.* files, quoted in full
3. Any leftover debug logging, TODOs, hardcoded values, or unused imports
Do not open a pull request.

You sign off on the pull request as its author, with the five checks above in its description. CI then runs the same gate, and an automated reviewer such as Bugbot plus a teammate review the pull request. How the team splits those checks is covered in version control and team collaboration in Cursor.

Should you fix forward or start over?

Starting over is a deliberate choice, not a defeat. Use these as defaults and adjust to your codebase.

Start over when	Fix forward when
The agent has failed at the same fix three times	The bug is small and isolated in otherwise good code
Understanding the tangled changes would take longer than redoing them	Most of the change is correct and already covered by passing tests
You realise the original prompt was wrong or incomplete	The work would be expensive to reproduce and one piece is wrong
The chat is long and keeps returning to failed approaches	The failure has a clear diagnosis you can hand over in one prompt

To start over cleanly: reset to the last good commit, remove the agent’s new files with git clean -fd (preview with git clean -nd), open a new chat, write the prompt with explicit file limits and acceptance checks, and reference the plan file if Plan Mode produced one. Keep conversations short in general; context management covers why long chats degrade.

When the problem is Cursor, not the code

Sometimes the agent is fine and the editor is not.

• The agent stops responding or errors on every request. Check your network and your plan’s usage, then pick a different model in the model picker to rule out one provider being down. See model selection.
• An MCP server fails or its tools disappear. Open the MCP server’s logs (see MCP setup in Cursor), fix the command or credentials they report, then restart the server or the editor.
• High CPU right after opening a large repository. Indexing is usually the cause and settles once it finishes. If it does not, exclude generated folders with an ignore file; see essential configuration.
• Work lost after a crash. Check git stash list and git reflog first. Committed work is recoverable from the reflog even after a hard reset.

What goes wrong when you recover from agent mistakes?

Symptom	Cause	Recovery
Files are restored but the app still fails the same way	The agent ran a migration, install, or generator in the terminal, which the checkpoint does not cover, or created new untracked files that git restore --staged --worktree . leaves in place	Undo the side effect by hand (roll back the migration, reinstall from the lockfile with npm ci), list new files with git clean -nd and delete them with git clean -fd, then rerun the gate
git reset --hard removed work you wanted	Uncommitted changes were not stashed	Committed work: git reflog. Staged but never committed: git fsck --lost-found sometimes finds it. Unstaged edits: restore a checkpoint if that chat is still open. From now on, run git stash push -u before every reset
The test is green, the bug is still there	The agent loosened the test instead of fixing the code	Restore the test from main with git restore --source main -- TEST_FILE (TEST_FILE is the path of the loosened test), then rerun the scoped-fix prompt with “do not modify tests”
A fresh chat makes the same wrong change again	The wrong assumption lives in the codebase or a stale rule, not in the old chat	Correct or add a project rule that states the convention, then retry
Tests pass alone and fail together after the fix	The agent introduced shared state: a module-level variable, an uncleared mock, a reused database connection	Ask the agent to find shared state between tests and isolate it; see testing patterns in Cursor
Debug logging reaches the pull request	Instrumentation was untagged, so nothing checked for it	Tag every temporary log line and make git grep -n --untracked "DEBUG-" part of the pre-PR gate

Where to go next after error recovery in Cursor

Version control and team collaboration in Cursor The next quick-start step: commit messages, merge conflicts, and pull requests with git checks that prove nothing was lost.

AI-assisted debugging in Cursor The full workflow for intermittent failures and race conditions: investigate read-only, reproduce, fix one cause.

Checkpoints and branching The rollback layer in depth, plus branches and worktrees for agent experiments.

Error recovery in Claude Code The same recovery routine in the terminal agent, built on Claude Code's own checkpointing.

The Codex version of this page is error recovery in Codex.