Cursor Debug Mode: Runtime Logs, Repro Steps & Targeted Fixes

Reach for Debug Mode when reading the code is not enough to explain the failure. It earns its keep on bugs that only show up at runtime, where collecting evidence beats another guess.

• Intermittent bugs where static reading of code is not enough.
• Regressions where behavior changed but the diff is unclear.
• Race conditions or environment-specific failures.
• Performance problems and memory leaks that need runtime profiling to understand.
• Cases where the agent already guessed wrong fixes twice in the same chat.

Performance and memory sit slightly apart from the rest of that list. The others are cases where reading the code could have worked and did not. A leak is not really readable, being a shape in behaviour over time, and the allocation site tells you nothing about which caller still holds the reference. If you are going to instrument anything, start there.

A prerequisite hides in the loop rather than in the list. Debug Mode asks you to reproduce the bug on demand, so a failure you saw once and cannot trigger again gives the instrumentation nothing to capture. Cursor frames the good case as a bug you can reproduce but cannot figure out, and that is the right way round.

It costs a round trip through you, which is the honest reason people skip it. You describe the bug, wait, run the repro, wait again. On something you would have found in ten minutes of reading, that is slower and it feels slower. I used to read that as an argument for trying normal Agent first. The better rule is to count guesses: switch on the second wrong fix rather than the fourth.

Debug Mode runs the same loop a careful engineer would: guess, instrument, reproduce, read the evidence, then fix. The difference is the agent drives most of it and waits on you for the one step it can't do, reproducing the bug.

1. 1Agent spins up a lightweight local web server whose only job is to accept requests.
2. 2Agent generates 4 to 5 hypotheses for the bug from your description.
3. 3Agent instruments the codebase with log lines (backend, frontend, any language) that POST JSON to the server to test each hypothesis.
4. 4You reproduce the bug using the steps Agent provides.
5. 5Agent reads the execution-path logs and confirms or denies each hypothesis.
6. 6Agent makes a surgically targeted fix touching only the broken lines.
7. 7You repro again; Agent strips all the log lines once confirmed.

Because instrumentation just needs to fire JSON at the server, Debug Mode works on anything that can emit a log, including compiled executables. It earns its keep on subtle bugs that span multiple services or sit nested between logic layers, where normal Agent modeCursor's full-capability mode: the AI can read the codebase, write and edit files, move them and run terminal commands. Contrast with Ask mode, which is read-only. Press Enter for the full definition.'s bias for action would guess and over-edit.

Step two is what separates this from a normal Agent run. Instead of committing to the first plausible cause, Debug Mode writes four or five candidates down and instruments for all of them at once, so one reproduction can eliminate several at a time. Let it skip ahead to a fix and you are guessing again, with extra logging.

Reproducing the bug is the step that stays yours, and doing it approximately is expensive. Logs collected from a slightly different path than the bug you are chasing are worse than no logs at all, because they read as evidence and they point somewhere real, just not at your problem. If the repro steps it hands you do not match how you actually hit the bug, say so before you run them.

The server those log lines talk to runs locally, inside a Cursor extension. The agent then reads what landed there, so treat the log contents the same way you treat anything else you hand a model.

Do not let it print secrets to prove a hypothesis.

Often, yes, and it's underrated. When someone hands you a screenshot, an error message or a console log you don't recognize, paste the image straight into chat (the image parser ingests it) and ask what it is. You can also use Cursor's in-app browser tool to take a screenshot, which drops it into context immediately. It works for any visual state: console output, a nuanced error, a broken UI.

Why it works has less to do with vision benchmarks than with search. An error you cannot name is hard to look up and trivial to point at, so the screenshot skips the step where you try to describe a stack trace you have never seen before well enough to find it. When the image is a rendered UI rather than text, say what you expected to see, since the picture only carries what is there.

Not yet. Through the JetBrains ACPAgent Client Protocol. An open standard that lets any IDE host any coding agent; Cursor uses it to run inside JetBrains/IntelliJ and Android Studio. Press Enter for the full definition. integration you get ask, regular agent and plan modes, but not Debug Mode: it isn't in the ACP spec yet. For Debug Mode, use the CLI or the Agents WindowCursor's surface listing your agent runs; open a run to read its diff and search transcripts from the command palette. Press Enter for the full definition.. When the spec adds it, Cursor will propagate it.

You can also tie Debug Mode to platform tooling: instruct it through a skill to use your MCPModel Context Protocol. A standard that lets an AI agent pull in context from outside the repo, like Jira tickets or internal docs. Press Enter for the full definition. tools as it runs the debug process. On iOS, for example, ask it to use the render-screen tool to validate the hypothesis it's testing, so the debugging is grounded in real simulator output rather than guesses.

Plan around the ACPAgent Client Protocol. An open standard that lets any IDE host any coding agent; Cursor uses it to run inside JetBrains/IntelliJ and Android Studio. Press Enter for the full definition. gap rather than waiting it out. If your team's day sits in JetBrains, run debugging sessions in the CLI or in the Agents WindowCursor's surface listing your agent runs; open a run to read its diff and search transcripts from the command palette. Press Enter for the full definition. open beside it, the same sidecar pattern mobile teams use next to Xcode. Cursor says it will propagate Debug Mode once the spec carries it, which is a roadmap statement and not a date.

The logs are only as good as the repro behind them. Give the agent the failure details up front and follow its reproduction steps exactly, so the evidence it reads matches the bug you actually hit.

• Paste stack traces, error strings and exact repro steps up front.
• State expected vs actual behavior in plain language.
• Follow reproduction steps precisely so logs match the failure.
• Re-run repro twice if the bug is flaky before asking for a fix.

Reproducing twice is not about being thorough, which is how the last line on that list tends to get read. A race condition that fires one run in three gives you logs from a passing run and a failing one, and the difference between those two is the actual finding. A single run has nothing to compare. Cursor's docs make the same point about repeated reproduction on the tricky ones.

When Debug Mode comes back with a confident wrong answer, check the instrumentation before you argue with the hypothesis. Log lines added to a code path your repro never entered produce a clean empty result, and a clean empty result looks exactly like a theory that has been ruled out.