What Is Cursor's Debug Mode? How to Use It, With Sample Prompts

What Debug Mode actually is

In December 2025, Cursor announced a new Agent mode called “Debug Mode.” Where regular Agent mode reads your code and jumps straight to a proposed fix, Debug Mode takes more of a detective’s approach — gathering runtime information first, then pinning down the cause.

Concretely, it works like this:

1. Describe the bug: give it the symptoms and reproduction steps, as specifically as you can
2. Form hypotheses: the agent reads through your codebase and generates several hypotheses about the cause
3. Add log instrumentation: it temporarily inserts logging code at the suspect locations to test each hypothesis
4. Reproduce the bug: you actually use the app to trigger the bug, and the agent collects the runtime logs
5. Pinpoint and fix the cause: based on what it collected (variable state, execution path, timing, and so on), it proposes a precise fix
6. Verify the fix: you reproduce the bug one more time — if it’s gone, the agent automatically removes all the log instrumentation it added; if not, it adds more logging and keeps narrowing it down

Thanks to this “hypothesize → instrument → reproduce → verify” loop, it’s said that rather than blindly rewriting hundreds of lines, you usually end up with a precise fix in the range of 2–3 lines.

How to turn it on

Press Shift + Tab to cycle modes and select “Debug.” You can also just click the mode and switch it directly.

When it’s the right tool

The official documentation points to Debug Mode being a good fit for:

• Bugs you can reproduce but can’t seem to root-cause
• Performance issues and memory leaks
• Problems where reading the code alone doesn’t reveal the cause

On the flip side, a simple error with an obvious stack trace is usually faster to resolve in regular Agent mode. A realistic rule of thumb: try your usual fix approach first, and switch to Debug Mode if that doesn’t get you anywhere.

How useful is it in practice?

Developers who use Debug Mode regularly point to a few things worth calling out:

• It works over HTTP-based text logs rather than depending on specific IDE features (like LSP), so it works with more or less any programming language or runtime — local environments, of course, but also over Remote SSH
• You can instrument both frontend and backend at once to track down bugs that span the two
• Some developers say hooking up external observability tools like Datadog or Sentry via MCP sharpens the results further

One developer ran into a bug where pagination on an external API integration always returned page one, no matter what. Debug Mode formed three hypotheses — a wrong JSON field name, a missing query parameter, a token not being passed correctly — and added log instrumentation to test them. After a few rounds of reproducing and collecting logs, it turned out the API actually used a different pagination scheme for aggregation endpoints versus regular queries, and the aggregation endpoints needed the token passed a different way entirely. Surfacing this kind of hidden spec mismatch from real data — the sort of thing that’s easy to miss just by reading the code — is where it really shines.

Sample prompts by scenario

Debug Mode gets more accurate the more specifically you describe the situation. Based on the usage patterns in the official documentation, here are some prompt examples by scenario.

Investigating from an error message

I'm getting "Cannot read property id of undefined" on line 45
of UserService.getProfile. Find the root cause and fix it.

The line where a stack trace surfaces an error and the place the actual cause lives are often different. Debug Mode traces back to “whatever called into that” to find the real cause.

Narrowing down a cause from logs

Processing for order ID 12345 is failing. The logs show:
inventory check passed → payment auth started → error here.
Find out exactly where after payment auth this is failing.

Hand it timestamped logs, and Debug Mode cross-references the order of events as it investigates.

Investigating from a support ticket

A customer reported that exporting their data produced an empty file.
Pro plan, account ID 12345. Check the export feature's code and
work out why the file might come out empty.

“Empty file” alone covers a lot of ground — zero records, a timeout, a silent failure, a corrupted download. Debug Mode lays out these possibilities and helps figure out what to check first.

Investigating an intermittent (flaky) test

This test is flaky — sometimes it passes, sometimes it fails.
Run it 20 times, collect the failures, and find the pattern.

Running a test by hand over and over is tedious, but that kind of repetitive work is exactly where Debug Mode earns its keep.

Investigating a frontend issue

Paired with Cursor’s browser tools, it can check the actual rendered screen, console errors, and even network requests.

The "Place order" button on the checkout page doesn't respond when clicked.
Take a screenshot, check the console errors, and find the cause.

Tips for preventing repeat issues and building institutional knowledge

To avoid re-investigating the same kind of issue over and over, it’s worth keeping a debugging rules file under .cursor/rules/. Jot down common bug patterns, internal queries you use for investigation, known flaky tests, and so on — Debug Mode will factor that in on future investigations.

Once a fix lands, it’s also worth asking Ask mode to explain why the bug happened in the first place, and whether the same pattern might be lurking elsewhere. That’s what actually prevents recurrences.

One more thing — not a Debug Mode feature specifically, but a common tip for getting Cursor to fix bugs well in general: a lot of people send a first prompt that just asks for an outline of the approach, without having it write any code yet. That lets you catch a misunderstanding on the agent’s part before any code gets written, which cuts down on rework.

Known limitations and things to watch for

There are reports that a lot of these limitations can be worked around, at least partially, by writing rules under .cursor/rules/*.mdc — things like “use this specific library” or “run the specified lint command cleanly after any change.” As for the CLI issue where input stops registering, pressing Escape usually frees it up, and pre-approving trusted commands in an allowlist — or turning on auto-approval — makes it easier to avoid altogether.

Wrapping up

Debug Mode builds a grounded debugging discipline into the agent: instead of “read the code and guess,” it’s “find the cause from data gathered by actually running the thing.” It’s strong against mysterious, stubborn bugs and performance problems, though for simple errors, regular Agent mode is sometimes faster — so knowing when to reach for which matters.

If you haven’t tried it yet, the next time you hit a bug where the cause just isn’t obvious, give Debug Mode a shot via Shift+Tab.