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

Use Debug Mode when reading the code is not enough to explain the failure. It pays off on bugs that only show up at runtime, where collecting evidence beats another guess.

• Bugs you can reproduce but can't explain by reading the code, including intermittent ones.
• Regressions where something used to work and the diff doesn't show why.
• Race conditions, timing issues and environment-specific failures.
• Performance problems and memory leaks that need runtime profiling to understand.
• Cases where the agent has already guessed wrong fixes twice in the same chat.

Performance problems and memory leaks differ from the rest of that list. In the other cases, reading the code could have worked and didn't. A leak is a pattern in behavior over time, so you can't read it off the code, and the allocation site doesn't tell you which caller still holds the reference. If you instrument anything, start there.

The loop has a prerequisite that the list doesn't show. Debug Mode asks you to reproduce the bug on demand, so a failure you saw once and can't trigger again gives the instrumentation nothing to capture. Cursor's docs describe the best case as a bug you can reproduce but can't figure out.

Each Debug Mode session costs a round trip through you. You describe the bug, wait, run the repro and wait again, which is slower than ten minutes of reading on a bug that reading would have found. That cost is a reason to try normal Agent first, but not for long. Count the guesses, and switch on the second wrong fix rather than the fourth.

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

1. 1Agent explores the relevant files and generates several hypotheses about the cause.
2. 2Agent adds log statements that send data to a local debug server running in a Cursor extension.
3. 3You reproduce the bug using the steps Agent provides.
4. 4Agent reads the logs and confirms or rules out each hypothesis.
5. 5Agent makes a targeted fix to the root cause, often just a few lines of code.
6. 6You run the repro again to verify. Once the fix is confirmed, Agent removes all the instrumentation.

In a Cursor webinar on QA and software testing, the presenter described that server as a lightweight web server whose only job is to accept requests. Log lines can go anywhere (backend, frontend, any language) as long as they can POST JSON to it, so Debug Mode works on anything that can emit a log, including compiled executables. The presenter said it helps most on subtle bugs that span several services or sit between layers of logic, 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 one is what separates this from a normal Agent run. Instead of committing to the first plausible cause, Debug Mode writes several candidates down and instruments for all of them at once, so one reproduction can rule out several. If it skips ahead to a fix, you are back to guessing, with extra logging.

Reproducing the bug stays your job, and doing it roughly is expensive. Logs from a slightly different path than the bug you are chasing are worse than no logs, because they look like evidence and point somewhere real, just not at your problem. If the repro steps it gives you don't match how you hit the bug, say so before you run them.

The agent reads whatever lands on that server, so treat the log contents like anything else you hand a model, and don't let it print secrets to prove a hypothesis.

Often, yes. When someone hands you a screenshot, an error message or a console log you don't recognize, paste the image into chat and ask what it is; the image parser reads it. Cursor's in-app browser tool can also take a screenshot, which goes into context right away. This works for any visual state: console output, an unfamiliar error or a broken UI.

A screenshot works because it gets around a search problem. An error you can't name is hard to look up and easy to point at, so the screenshot skips the step where you describe a stack trace you have never seen well enough to find it. When the image shows a rendered UI rather than text, say what you expected to see, because the picture only shows what is there.

Not yet. Cursor's 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. reference lists three modes for ACP sessions (agent, plan and ask), so the JetBrains integration, which runs on ACP, has no Debug Mode. For Debug Mode, switch to Cursor's CLI, editor or 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..

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 instead of waiting for it to close. If your team works in JetBrains all day, 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. In a Cursor webinar on mobile development, the presenter said Debug Mode isn't in the ACP spec yet and will come to ACP once the spec supports it. That is a roadmap statement without a date.

The same webinar tied Debug Mode to platform tooling. A skill can tell Debug Mode 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 while it debugs. On iOS, for example, ask it to check each hypothesis with the screenshot tool from Xcode's MCP server, so the debugging rests on real simulator output instead of guesses.

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 hit.

• Paste stack traces, error strings and exact repro steps up front.
• State expected vs actual behavior in plain language.
• Follow the reproduction steps precisely so the logs match the failure.
• Reproduce a flaky bug at least twice before you ask for a fix.

The repeat run gives the agent something to compare. A race condition that fires one run in three can give you logs from a passing run and a failing one, and the difference between them is the finding. A single run has nothing to compare against. Cursor's docs say repeated reproduction may help the agent with tricky problems like race conditions.

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