Debugging and Error Recovery

The agent just refactored your authentication module. It moved functions between files, updated imports, and added a new validation layer. The tests pass — but the login page throws a white screen in the browser. The terminal shows no errors. The agent is confident its changes are correct. Welcome to the reality of AI-assisted development: the code looks right, passes lint, and breaks in ways that are subtle and frustrating. This article is your field guide to diagnosing and recovering from exactly these situations.

What You’ll Walk Away With

• A systematic approach to debugging AI-generated code that is different from debugging human-written code
• Mastery of Cursor’s checkpoint system for instant rollback
• The debug mode workflow for tricky bugs that require runtime evidence
• A “pre-PR” cleanup pattern that catches issues before they reach your team
• Recovery strategies for when the agent is stuck in a loop

The Nature of AI-Generated Bugs

AI-generated bugs are different from human bugs. Understanding the difference changes how you debug:

Human Bugs	AI-Generated Bugs
Typos and off-by-one errors	Structurally correct but semantically wrong
Forgotten edge cases	Confident about wrong assumptions
Copy-paste mistakes	Consistent pattern applied to wrong context
Logic errors in complex flows	Working code that solves the wrong problem

The most dangerous AI bugs are the ones that look perfectly reasonable. The code compiles, the types check, the tests pass — but the behavior is subtly wrong because the agent misunderstood a requirement or applied a pattern from the wrong part of your codebase.

Checkpoint Recovery

Cursor creates a checkpoint before every set of changes the agent makes. This is your most important recovery tool.

How Checkpoints Work

Every time the agent modifies files, Cursor saves the state of all affected files. You can see checkpoints in the conversation timeline as numbered markers.

Restoring a Checkpoint

1. Find the checkpoint in the conversation timeline (before the problematic change)
2. Click the Restore button next to it
3. All files revert to their state at that checkpoint
4. Your conversation history is preserved — only the files change

Checkpoint Strategy

For complex tasks, create explicit restoration points by committing to git between phases:

[Agent builds database schema] --> git commit
[Agent builds API endpoints] --> git commit
[Agent builds frontend] --> git commit

If the frontend work goes wrong, you can restore to the checkpoint and still have the API work safely committed in git.

Note

Checkpoints are local to Cursor and your session. Git commits are permanent and shareable. Use checkpoints for quick experimentation, git commits for real milestone preservation.

Debug Mode

Cursor offers a dedicated Debug mode for bugs that are hard to reproduce or understand from reading the code alone. Debug mode takes a different approach from standard Agent mode: instead of immediately writing fixes, it instruments your code, collects runtime evidence, and then makes targeted fixes.

When to Use Debug Mode

• The bug is reproducible but the cause is not obvious from the code
• Race conditions or timing-dependent issues
• Performance problems that require profiling
• Regressions where something used to work and now does not

How Debug Mode Works

Switch to Debug mode from the mode picker (Cmd+.).

1. Describe the bug

   The login form submits successfully (200 response) but the user is not
   redirected to the dashboard. The session cookie appears to be set correctly.
   This started happening after the auth refactor yesterday.

2. Agent generates hypotheses

   The agent explores relevant files and proposes multiple possible causes.

3. Agent adds instrumentation

   It inserts targeted log statements that send data to a local debug server running in the Cursor extension.

4. You reproduce the bug

   The agent tells you exactly what steps to take. Follow them precisely.

5. Agent analyzes the logs

   After reproduction, it reviews the collected data and identifies the root cause.

6. Agent makes a targeted fix

   Instead of guessing, it fixes the exact line causing the issue, based on runtime evidence.

7. Verify and clean up

   Reproduce again to confirm the fix. The agent removes all instrumentation.

Copy-paste prompt for a debug mode session

The payment webhook handler is intermittently returning 500 errors.
It happens roughly 1 in 10 times. The logs show "TypeError: Cannot read
property 'id' of undefined" but the request body always contains the expected fields.
I suspect a race condition or timing issue.

Add instrumentation to trace the exact execution path and help me
reproduce the failure.

The Pre-PR Cleanup Pattern

Before submitting a PR, run the agent through a comprehensive cleanup pass. This catches issues that slip through individual task conversations.

Copy-paste prompt for pre-PR cleanup

Run our full pre-PR check: npm run build && npm run lint && npm test

If anything fails, fix it and rerun until everything passes.
Then review all the changes on this branch compared to main and
flag any potential issues: missing error handling, unused imports,
hardcoded values, or deviations from our project conventions.

This single prompt, with auto-run enabled, handles:

1. TypeScript compilation errors
2. Lint violations
3. Test failures
4. A final code review pass

The agent iterates on each failure until the build is clean. The review at the end catches semantic issues that linters miss.

Common Error Patterns and Fixes

Pattern 1: Agent Loops on the Same Error

The agent makes a change, the test fails, it reverts, tries a different approach, fails again, and starts repeating itself.

Fix: Press Escape to stop it. Start a new conversation with more specific context:

@src/auth/session.ts The test "should redirect after login" is failing
because the session middleware expects req.session to be populated,
but the test mock does not set it up. Fix the mock, not the production code.

The key insight: when the agent loops, it has lost track of the problem. A fresh conversation with a specific diagnosis breaks the loop.

Pattern 2: Code Compiles but Behavior is Wrong

Everything passes in the terminal but the feature does not work in the browser or when manually tested.

Fix: Use Debug mode to add instrumentation, or ask the agent to add logging:

The form submission works in tests but fails in the browser.
Add console.log statements at each step of the form submission handler
in @src/handlers/form-submit.ts so I can see where it diverges
from expected behavior. I'll paste the console output back to you.

Run the application, reproduce the issue, copy the console output back into the chat. The agent now has runtime evidence instead of static analysis.

Pattern 3: Agent Changes Too Many Files

You asked for a small change and the agent rewrote half the codebase.

Fix: Restore the checkpoint immediately. Then be more specific:

Only modify src/services/billing.ts. Do not change any other files.
Add a retry mechanism to the processPayment function. Use the
existing retry utility in src/utils/retry.ts.

Constraints like “only modify” and “do not change” are instructions the agent respects. The broader your prompt, the more files it considers fair game.

Pattern 4: Flaky Tests After AI Changes

Tests that were passing now fail intermittently.

Fix: This often indicates the agent introduced timing dependencies or shared state:

@src/services/billing.test.ts These tests are now flaky -- they pass
individually but fail when run together. Check for shared state between
tests (database connections, module-level variables, un-cleared mocks)
and add proper isolation.

Pattern 5: Import Errors After Refactoring

The agent moved code between files and got some imports wrong.

Fix: Let the agent use the TypeScript compiler to find and fix all import issues:

Run tsc and fix all import errors. Do not change any logic,
only fix the import paths and missing exports.

The “Start Over” Decision

Sometimes the best debugging strategy is to throw away the broken changes and try again with a better prompt. This is not failure — it is a deliberate strategy.

Start over when:

• The agent has made more than 3 failed attempts at the same fix
• The changes are so tangled that understanding them takes longer than redoing them
• You realize the original prompt was wrong or incomplete

Do not start over when:

• The issue is a small, isolated bug in otherwise good code
• Most of the changes are correct and only one piece is wrong
• The agent has invested significant work that would be expensive to reproduce

To start over cleanly:

1. Restore the earliest checkpoint (or git stash)
2. Start a new conversation
3. Write a more specific prompt with explicit constraints
4. Reference the plan file if you have one

Caution

Resist the urge to keep correcting the agent in a long conversation. After 3-4 correction attempts, the conversation context is polluted with failed approaches. A fresh start with a better initial prompt almost always produces a better result faster.

Preventing Bugs Before They Happen

The best debugging is the debugging you never have to do. These practices dramatically reduce the frequency of AI-generated bugs:

1. Write project rules for every convention — if the agent keeps making the same mistake, add a rule
2. Use Plan mode first — planning catches architectural mistakes before code is written
3. Reference existing patterns — @ references to existing files give the agent concrete examples to follow
4. Keep conversations short — long conversations lead to context degradation and confused output
5. Commit frequently — small commits mean small rollbacks
6. Run tests continuously — with auto-run enabled, the agent catches its own mistakes immediately

When Cursor Itself Has Problems

Occasionally the issue is with Cursor rather than the generated code:

AI not responding: Check your subscription status and internet connection. Switch models if one API is down.

High CPU usage: Indexing may be running. Check Settings then Indexing and Docs. If it persists, try disabling extensions with cursor --disable-extensions.

MCP server errors: Check the Output panel (View then Output, select the MCP server). Restart Cursor if a server is stuck.

Lost changes after a crash: Check git stash, Cursor’s checkpoint history, and the backup files in ~/.config/Cursor/Backups/.

What’s Next

You have completed the Cursor Quick Start. From here:

Productivity Patterns

Deep-dive into keyboard shortcuts, prompt templates, and time-saving workflows for daily development.

Advanced Techniques

Explore agent mode deep dives, custom MCP servers, and large codebase strategies for complex projects.

Shared Workflows

Learn cross-tool workflows that work across Cursor, Claude Code, and Codex.

Tips and Tricks

Browse the tips collection for battle-tested patterns from experienced Cursor users.