How to Debug Code with Cursor

Some bugs survive a quick Agent patch. You can reproduce the failure, but reading the code does not reveal why it happens. Timing, cached state, and environment specific behavior fall in this bucket. Cursor Debug mode treats these bugs differently from normal Agent mode. Instead of guessing a fix, Agent forms hypotheses, adds temporary logging tied to a local debug server, asks you to reproduce, reads runtime evidence, then patches narrowly.

Switch to Debug with Shift+Tab from the Agent input or the mode picker. Bring the same detail you would give a teammate sitting beside you. Explore summary at /explore/cursor under Debug mode.

When Debug beats Agent

• You can reproduce the bug but the cause is not obvious from static reading
• Race conditions or order dependent async behavior
• Performance regressions or memory growth you need to observe live
• Regressions where something used to work and the diff is too large to eyeball

The Debug workflow

Work in this order: reproduce locally and confirm you can trigger the failure, open Debug mode with full context, let Agent add instrumentation, follow reproduction steps exactly, review logs with Agent, confirm the minimal fix, rerun reproduction to verify, ask Agent to remove logging, add a regression test if the repo supports it. Skipping reproduction produces logs that miss the real failure path.

Phases inside Debug mode

• Explore and hypothesize from code and your report
• Add instrumentation tied to the local debug server
• You reproduce with exact steps Agent provides
• Agent analyzes collected logs
• Targeted fix lands with small diff
• Verify fix, remove instrumentation, optional regression test

What the first message must include

• Ordered steps to reproduce
• Expected behavior stated plainly
• Actual behavior stated plainly
• Error text, stack traces, or console output when available
• Browser, Node, or OS version when the bug is environment specific
• What you already tried so Agent does not repeat dead ends

Debug mode:
Bug: ProductList fetch loop in development.
Steps: open /shop, watch network tab.
Expected: one GET /api/products on mount.
Actual: repeated GET every render.
Environment: React 18 strict mode, Next.js 14.
@src/components/ProductList.tsx attached.

Example: intermittent authorization failure

Debug mode:
Bug: /api/settings returns 401 about one request in twenty under load.
Expected: valid session always passes middleware.
Actual: sporadic 401 with same cookie header.
Already tried: confirmed cookie not expired in logs.
Reproduce: run k6 script settings-load.js for 60 seconds.
@src/middleware.ts @src/app/api/settings/route.ts

Example: wrong cart total after removeItem

Debug mode:
Steps: add two SKUs, remove one, read displayed total.
Expected: sum of remaining line items.
Actual: total includes removed item until navigation.
@src/store/cartStore.ts @src/components/CartSummary.tsx
Add logging only first; no fix until logs confirm root cause.

Example: ask for logging before fix

Debug mode:
WebSocket reconnect storm after laptop sleep.
Expected: single reconnect with backoff.
Actual: dozens of connections in server logs.
Phase 1: instrument connect/disconnect paths only.
Phase 2: propose minimal fix after we see log pattern.

Follow Agent reproduction steps exactly

After instrumentation lands, run the steps Agent provides in order. If you skip a step, logs may look healthy while the bug still exists in the path users hit. For flaky bugs, reproduce multiple times when Agent asks. Tell Agent if strict mode, hot reload, or a service worker changes behavior.

Example: performance regression

Debug mode:
Page /dashboard time to interactive regressed from 2s to 9s after commit abc123.
Steps: cold load with cache disabled, Chrome performance tab open.
Expected: main thread idle within 3s.
Actual: long task from @src/features/charts/ChartPanel.tsx.
Compare behavior on commit abc122 if needed.

Example: stale cache after mutation

Debug mode:
After POST /api/items, list view shows old count until hard refresh.
Reproduce with two browser tabs open.
@src/features/items/useItemsQuery.ts @src/app/api/items/route.ts
Log cache keys on read and write before proposing fix.

When Agent mode alone fails

If Agent guessed three times without fixing a reproducible bug, switch to Debug instead of stacking fix up prompts. Debug is designed for evidence gathering. If Debug reveals the fix spans many files, finish the patch in Agent with the root cause summary pasted from Debug chat.

Review the fix and cleanup

Debug mode aims for a small patch tied to evidence, not a broad rewrite. After you confirm the fix, Agent should remove temporary logging. Ask for one regression test that would have failed before the patch. Run your usual test command before merge. See /blog/how-to-test-and-verify-changes-made-by-cursor.

Fix confirmed manually.
Remove all debug instrumentation.
Add one test that fails on the old behavior.
Run npm test -- --testPathPattern=ProductList

When Debug is the wrong tool

• Typo or missing import: Agent with narrow scope
• You only need an architecture explanation: Ask
• You cannot reproduce the bug yet: reproduce first, then Debug
• You need a multi file feature design: Plan, then Agent or Debug as needed

Common mistakes

• Pasting only the error string with no code attached
• Changing several unrelated things after the first patch
• Ignoring environment details on browser or mobile bugs
• Declaring victory before rerunning reproduction steps
• Leaving debug logging in the branch after the fix

Handoff from Debug to Agent

When Debug identifies root cause but the fix spans modules, paste the Debug conclusion into a fresh Agent prompt with @ files attached. Include the log excerpt that proved the cause so Agent does not reopen settled questions.

Agent: apply fix for duplicate fetch root cause from Debug session.
Root cause: effect missing dependency array on line 42.
Scope: @src/components/ProductList.tsx only.
Add regression test. Run npm test -- --testPathPattern=ProductList.

Environment and tooling notes

Tell Debug when docker compose, multiple services, or a specific browser version matters. Include whether the bug appears only in production builds or also in development. Debug instrumentation assumes you can run the reproduction locally while the debug server receives logs.

Agent guesses vs Debug evidence

Standard Agent mode may propose a plausible fix from code reading alone. Debug mode is for when that fix failed or when the bug depends on runtime order you cannot see statically. Switch modes instead of repeating fix it prompts that do not address evidence.

Debug mode follow up:
Previous Agent patch did not stop duplicate fetch.
Logs should show whether effect runs twice or fetch called from two paths.
Do not apply a new fix until logs identify which path.

Strict mode and development only bugs

React strict mode double mounting causes many false bug reports. Tell Debug when the issue appears only in development. Include whether production builds show the same symptom. Debug logs should distinguish double invoke from true duplicate network calls.

Debug mode:
Bug appears only when React strict mode enabled in dev.
Production build behavior unknown.
Compare mount count logs between dev and production build if possible.

When to hand off from Debug to Agent

Once logs show root cause and you agree on the fix, switch to Agent for the edit if Debug has not already applied it. Agent can implement the minimal change while instrumentation is still present. Ask Agent to remove debug logs only after tests pass. Mixing Debug diagnosis with Agent broad refactors in one prompt usually wastes the evidence Debug collected.

Debug found: checkout total uses stale cart state after merge.
Agent task: fix merge logic in cartStore.ts only.
Keep Debug logs until npm test -- --testPathPattern=checkout passes.
Then remove instrumentation in a separate commit.

Related: /blog/cursor-ask-vs-agent-vs-plan-which-mode-should-you-use, /blog/how-to-use-cursor-agent-to-build-and-refactor-code, /blog/how-to-test-and-verify-changes-made-by-cursor.