CursorDebuggingLevel 2: Context

When Should You Use Debug Mode in Cursor?

Use Debug mode when you can reproduce a bug but can't explain it, or when normal Agent keeps offering fixes that don't work. It doesn't write a fix straight away. It generates hypotheses, adds log statements, asks you to reproduce the bug, and reads what actually happened before it changes the code.

Prompt to copy
[Describe the bug in plain language.]

How to reproduce: [exact steps]
Expected: [what should happen]
Actual: [what happens, plus any error message or stack trace]
How often: [every time / roughly 1 in 5 / only under load]
What I've ruled out: [anything you've already checked]
  1. 1Hypothesize
  2. 2Add logs
  3. 3You reproduce
  4. 4Analyze logs
  5. 5Targeted fix
  6. 6Verify, clean up
Then repeat
The six steps in Cursor's Debug Mode docs. You come in at the reproduction step.

Try it now

  1. 1Open Agent with Cmd+I (Ctrl+I), and press Shift+Tab until the mode shows **Debug**. You can also use the mode picker dropdown.
  2. 2Send the prompt above. Wait for it to list hypotheses and add log statements.
  3. 3Follow its reproduction steps exactly, then tell it you're done. It worked if the explanation cites values from the logs, and the log statements are gone after you confirm the fix.

Use it when

Cursor names four cases: bugs you can reproduce but can't figure out, race conditions and timing issues, performance problems and memory leaks, and regressions where something used to work. It's also a good next step after one failed attempt in Agent.

Skip it when

A clear error with an obvious cause, since pasting the stack trace into Agent is faster. It's also a poor fit when you can't trigger the bug yourself at all, because the method depends on you reproducing it while logs run. Work on the reproduction first.

Why it works

Plain Agent reasons from reading code, and timing bugs, memory leaks and regressions often don't show up there. Debug mode gets runtime evidence. Cursor's docs say its log statements send data to a local debug server running in a Cursor extension, so the logs come back to the agent without you copying them. Because the fix is based on observed values, it's often just a few lines. After you confirm the fix, the agent removes all the instrumentation.

Example

Cursor's course offers a case like this: some checkouts fail now and then with no consistent error, and a customer may just land on a blank confirmation page. Debug mode might log the order state and the timing around payment confirmation, then ask you to place several test orders. A failing run can then be compared with a good one.

Going further

Reproduce more than once for timing bugs. The docs say multiple runs may help it identify tricky problems like race conditions, because a single run shows only one interleaving. For a stubborn bug, Cursor's course also suggests selecting several models from the agent dropdown and running the same brief on each. Each works in isolation, and Cursor suggests which fix it thinks is best, though the course says to evaluate the reasoning rather than only the final answer.

Common mistakes

  • Doing your own version of the steps. The docs say to follow them exactly, so the logs capture the actual issue.
  • Leaving out expected versus actual behavior, which the instrumentation depends on.
  • Using it for an error message that already names the cause, which adds steps for no gain.
  • Committing before the cleanup step, which can put debug log statements into your history.

Sources

Checked 6 November 2026. Products change often, so confirm details with the vendor.

Related

Beyond the course