The bug that will not let itself be read
A search field sometimes shows the results of an old search. There is no console error, no stack trace, and the bug disappears when you look at it calmly. An assistant you ask to "fix it" has nowhere to start, and if it answers with confidence it is guessing. Debugging with Cursor's help works when the assistant does not guess but gathers evidence, and when you are the one who interprets that evidence.
This article follows the method that Cursor's documentation describes for its Debug Mode (hypotheses, instrumentation, reproduction, targeted fix, verification) and applies it to two typical Angular bugs, reproducible in a few seconds: a race condition between requests and a subscription that is never closed. The code was run, so the outputs you see are real. How much time you save depends on the bug and on the discipline you work with: there is no speed-up factor valid for everyone and you will not find one here. You will find a method you can repeat instead; to automate its checks there is the fifth article of the series, on hooks.
Debug Mode: what it really does
Debug Mode was introduced with Cursor 2.2, on 10 December 2025 according to the official changelog. The documentation presents it as a way to find the root cause of bugs that are hard to reproduce or to understand: instead of writing code right away, the agent generates hypotheses, adds log statements and uses information gathered at runtime to pinpoint the problem before intervening. You select it from the agent's mode picker, or with Shift+Tab.
- Explore and hypothesize: the agent reads the relevant files and formulates several hypotheses about the cause.
- Instrument: it adds logs that send data to a local debug server, run by a Cursor extension.
- It asks you to reproduce the bug, with precise steps, so that real behavior is captured.
- It analyzes the collected logs and identifies the cause based on the evidence.
- It makes a targeted fix, often a few lines.
- You redo the reproduction to verify; once you confirm, the agent removes all the instrumentation.
The order is the substance: the fix comes at the fourth step, after the data has ruled out at least one hypothesis. The third step is the one many people skip with a generic assistant: you do the reproduction yourself, and it is what keeps you inside the loop. That is why the documentation recommends running the steps exactly as given, repeating the reproduction several times for timing bugs and describing expected and observed behavior precisely.
When to use it, and when not
According to the documentation the mode works best with bugs you can reproduce but cannot explain, with race conditions and timing issues, with performance and memory problems that need a runtime profile and with regressions. It is not the right choice for a compile error: if the compiler tells you the line and column, instrumenting the program is extra work. In that case it is enough to select the code and describe the fix in the chat. The mode also has a cost you do not see in the list: the bug must really be reproduced, and a failure that shows up once a month in production cannot be reproduced on demand.
The same method by hand: a race condition
To understand what the agent automates, it is worth doing it once without it. The case is the search field:
every keystroke fires a request, and the responses do not arrive in the order they left. You type
"an", then "ang", then "angular"; the request for "an" returns many rows and takes longer, so its
response arrives last and overwrites the right one. In the code below the server latency is simulated
with timer (600, 300 and 100 milliseconds), so the failure is deterministic instead of depending on the
network.
import { Observable, Subject, timer, map, mergeMap, switchMap } from "rxjs";
// Simulated server latency: the shortest query is also the slowest,
// as happens when "an" returns thousands of rows and "angular" only a few.
const LATENZA_MS: Record<string, number> = { an: 600, ang: 300, angular: 100 };
export function cerca(q: string): Observable<string> {
return timer(LATENZA_MS[q]).pipe(map(() => `results for "${q}"`));
}
// Buggy version: every keystroke fires a request and none is ever cancelled
export const conBug = (tasti: Observable<string>) => tasti.pipe(mergeMap(cerca));
// Fixed version: a new request cancels the previous one still in flight
export const corretta = (tasti: Observable<string>) => tasti.pipe(switchMap(cerca));
export async function digita(
costruisci: (t: Observable<string>) => Observable<string>,
): Promise<string[]> {
const tasti = new Subject<string>();
const arrivati: string[] = [];
costruisci(tasti).subscribe((r) => arrivati.push(r));
for (const q of ["an", "ang", "angular"]) {
tasti.next(q);
await new Promise((ok) => setTimeout(ok, 50)); // one keystroke every 50 ms
}
await new Promise((ok) => setTimeout(ok, 800)); // let all the responses arrive
return arrivati;
}
The two versions differ by one word. mergeMap keeps all the inner requests alive and
forwards each response as it arrives: it is the equivalent of one subscribe per keystroke.
switchMap, as the operator's documentation in the RxJS source says, stops emitting from the
previous inner stream when a new one arrives, so an old response can no longer appear. The
digita function is the test bench: one keystroke every 50 ms, then a wait of 800 ms so that all the
responses have time to arrive.
The test is also the method's "instrumentation": printing the arrival order is the log you need to tell the hypotheses apart. With the wrong version the response for "an" arrives last, and the screen shows the wrong search; with the fixed one a single response remains.
import assert from "node:assert/strict";
import { conBug, corretta, digita } from "./ricerca.ts";
for (const [nome, versione] of [["buggy", conBug], ["fixed", corretta]] as const) {
const arrivati = await digita(versione);
console.log(`${nome}: arrivals in order ->`, arrivati);
const ultima = arrivati.at(-1);
try {
assert.equal(ultima, 'results for "angular"');
console.log(`${nome}: OK, the screen shows the latest search`);
} catch {
console.log(`${nome}: FAILED, the screen shows ${ultima}`);
}
}
// Output (node prova.ts, Node 24.19.0, rxjs 7.8.2; identical in two runs):
// buggy: arrivals in order -> [ 'results for "angular"', 'results for "ang"', 'results for "an"' ]
// buggy: FAILED, the screen shows results for "an"
// fixed: arrivals in order -> [ 'results for "angular"' ]
// fixed: OK, the screen shows the latest search
The output contains the diagnosis: in the buggy version the responses arrive in the reverse of the order they were sent (angular, ang, an), and the last one, the one the screen shows, is the oldest. In the fixed version only one arrives. It is also the regression test the method asks for: it fails without the fix, passes with it. The failure shows up "only on a slow network" because when latency does not depend on the request the responses tend to stay in order, and that is what makes it intermittent. This test depends on time: margins of 150 ms or more between arrivals keep it stable even on a loaded machine, but a margin of a few milliseconds would make it an unstable test in turn.
The subscription that stays alive
The second bug is one of the most common in Angular: a component subscribes to a long-lived stream, for example
a service's, and when the component is destroyed the subscription goes on. Every visit to the page
leaves one more behind. The modern fix is takeUntilDestroyed, which closes the subscription
when the DestroyRef is destroyed. The program counts the subscriptions still alive and does
it outside a component, by creating an environment injector, whose DestroyRef behaves like a component's.
import { DestroyRef, EnvironmentInjector, Injector, createEnvironmentInjector } from "@angular/core";
import { takeUntilDestroyed } from "@angular/core/rxjs-interop";
import { Observable } from "rxjs";
// A "long-lived" stream (a service): count how many subscriptions are still alive
let vive = 0;
const flusso$ = new Observable<number>(() => {
vive++;
return () => { vive--; };
});
// Simulates a component: it has its own DestroyRef, which Angular destroys together with the component
function creaComponente(conCleanup: boolean): EnvironmentInjector {
const componente = createEnvironmentInjector([], Injector.NULL as EnvironmentInjector);
const destroyRef = componente.get(DestroyRef);
const sorgente$ = conCleanup ? flusso$.pipe(takeUntilDestroyed(destroyRef)) : flusso$;
sorgente$.subscribe();
return componente;
}
for (const conCleanup of [false, true]) {
vive = 0;
for (let i = 0; i < 3; i++) creaComponente(conCleanup).destroy(); // create and destroy 3 components
console.log(`takeUntilDestroyed ${conCleanup ? "present" : "absent "}: live subscriptions after 3 destructions = ${vive}`);
}
// Output (node leak.ts, Node 24.19.0, @angular/core 22.2.6, rxjs 7.8.2):
// takeUntilDestroyed absent : live subscriptions after 3 destructions = 3
// takeUntilDestroyed present: live subscriptions after 3 destructions = 0
The stream returned by new Observable increments a counter on activation and decrements it
in the teardown function. Without takeUntilDestroyed, after three "components" created and destroyed
three subscriptions remain alive; with the operator, zero. It is the same measurement you would make with a heap snapshot
in Chrome DevTools, but here it is a number that a test can compare. In the real component you write
inject(DestroyRef) or omit the argument, because in an injection context the operator
works it out by itself, as the Angular documentation explains.
Providing context: the first message
With or without Debug Mode, the quality of the first request decides how much work you waste. The text below is an example for the search bug: it states expected and observed behavior, the frequency, the last suspect change and the files, and above all it asks for hypotheses instead of a fix.
Expected behavior: the list shows the results of the last search typed.
Observed behavior: sometimes the list shows the results of an earlier search.
Frequency: intermittent, only on a slow network.
Last related change: the commit that introduced the search field.
Error: none in the console.
Likely files: @search.component.ts and @search.service.ts
Propose three hypotheses about the cause, in order of probability, and tell me which log
you would add to tell them apart. Do not fix anything yet.
The last line is the most important: "do not fix anything yet" stops the assistant from jumping to the fix
line, and gives you three hypotheses to compare with the logs. The references with @ add the files to the
context. Citing the suspect commit and attaching the whole error, not just the first line, narrows the field right away.
- Expected and observed, both: the contrast is the definition of the bug.
- Frequency and environment: a failure "only in production" or "only on a slow network" suggests a race.
- Last related change: narrows the space of hypotheses more than any other piece of data.
- Full output: the whole stack trace, not just the red line.
For the intermittent bug the first three matter most, because they say when and where to look; for an error with a clear stack trace the fourth becomes the first. None of these data is special to Cursor: they are what you would give a colleague you ask for help, for the same reason.
Bugbot: review on pull requests
If Debug Mode helps after the bug has shown up, Bugbot works earlier: it analyzes the diff of a pull
request and leaves comments with explanations and suggested fixes. According to the
documentation it starts on its own at every PR update, or on request with a comment
"cursor review" or "bugbot run". It skips PRs that are too large, asking you to split them, and ignores files marked
linguist-generated. Prices depend on the plan and changed in May 2026: you find them on the pricing
page, not here.
To guide it you write rules in a .cursor/BUGBOT.md file. Bugbot always includes the one in the root
and the ones found by walking up from the modified files, so a BUGBOT.md in frontend/ applies
only to changes to the frontend. One detail contradicts a widespread habit: the .mdc project rules
in .cursor/rules/ do not apply to Bugbot, which reads only its own files.
# Review rules for this repository
## Angular
- Flag every subscribe() on a long-lived Observable that does not go through
takeUntilDestroyed() or an async pipe.
- Flag an HTTP request fired inside a nested subscribe():
use switchMap (or concatMap, if order matters).
## Project conventions
- Components do not call HttpClient: they go through a service.
- Browser storage is used only through StorageService.
The rules are free text, like a brief for a reviewer: the more specific and checkable on the diff they are, the fewer
false alarms. "Flag every subscribe() without takeUntilDestroyed" is checkable;
"write clean code" is not. The block is a schema to adapt to your project.
Autofix is the feature that starts a cloud agent to fix the bugs found. The documentation provides three settings: off, fix on a new branch, or commit to the PR's branch, the latter with a maximum of three attempts per PR to avoid loops. Not every platform offers all of them (on GitLab and Bitbucket there is only the commit to the existing branch) and Autofix requires additional paid usage. The new branch is the prudent choice: the fix arrives as a proposal you review, not as a commit you find waiting for you.
Checkpoints and Git: two different safety nets
During a session the agent creates checkpoints before significant changes: snapshots of the modified files, which you return to from the chat history. The documentation specifies two limits that matter: restoring affects only files, not messages, and checkpoints are local and separate from Git, so they do not replace a commit. The practical rule for exploratory debugging is to make a commit (even a temporary one) before trying fix hypotheses, and to use checkpoints to go back within the session.
Do not trust the first fix
A plausible fix is not a correct fix. The assistant can suppress the symptom (a
try/catch that swallows the error, an any that silences the compiler) without touching
the cause. A regression test written before the fix is the only check that does not depend on trust.
You can codify your rules once in a project rule: the documentation asks for .mdc files
with a description, globs and alwaysApply header, and
ignores a plain .md in the same folder.
---
description: How to propose a fix for a bug in this project
globs: src/**/*.ts
alwaysApply: false
---
- Before fixing, write the root cause in at most three sentences.
- Every fix comes with a test that fails without the fix.
- Do not modify a test to make it pass: fix the code.
- Do not silence a type error with any or with the ! operator.
With alwaysApply: false and a description, the agent decides on its own when the rule is
relevant; the globs limit it to TypeScript files. The rule does not make the mistake impossible: it makes
it rarer and easier to notice in review. The rules themselves are the subject of the
second article of the series.
What you can do now
You know what Debug Mode does and when it is worth it, and you have seen the same method applied by hand to a
race condition and to a subscription that stays alive, with a test that fails before and passes after. You know how to
guide Bugbot with .cursor/BUGBOT.md and why .mdc rules do not reach it, and you can
tell Cursor's checkpoints apart from a commit. If the bug depends on data that lives in a database, the
sixth article, on MCP shows how to give it to the agent read-only;
to choose between Cursor and the other tools move on to the
comparison of Cursor, Windsurf and Copilot, and for the
full picture of a project to the professional
workflow in Angular.
Frequently asked questions
What is Cursor's Debug Mode and when was it introduced?
It is an agent mode that first formulates hypotheses, then adds logs, asks you to reproduce the bug and only afterwards proposes a targeted fix. It arrived with Cursor 2.2, on 10 December 2025 according to the changelog.
How do you keep a race condition from coming back?
With a test that reproduces the wrong arrival order and fails without the fix. In the search case, different simulated latencies and the switchMap operator, which discards the responses of superseded requests, are enough.
Do the rules in .cursor/rules also apply to Bugbot?
No. Bugbot's documentation says that .mdc project rules do not apply to its reviews: to guide it you use .cursor/BUGBOT.md, or the rules defined in the dashboard.
The same series also includes Cursor IDE: The Complete Developer Guide.
Sources
- Cursor, documentation: Debug Mode - the six phases, the recommended use cases and the tips on reproduction, consulted on 2026-11-13
- Cursor, changelog 2.2 - introduction date of Debug Mode (10 December 2025), consulted on 2026-11-13
- Cursor, documentation: Bugbot - activation, limits, rules in
.cursor/BUGBOT.md, Autofix modes, consulted on 2026-11-13 - Cursor, documentation: Agent, Checkpoints section - local nature of checkpoints and the distinction from Git, consulted on 2026-11-13
- Cursor, documentation: Rules -
.mdcformat and thedescription,globs,alwaysApplyfields, consulted on 2026-11-13 - RxJS 7.8.2, switchMap source - the cancellation behavior of the previous inner stream, consulted on 2026-11-13
- Angular, API: takeUntilDestroyed - closing the subscription when the context is destroyed, consulted on 2026-11-13
The two programs were run with Node 24.19.0, rxjs 7.8.2 and @angular/core 22.2.6 in a temporary folder, twice each, with identical output. Debug Mode and Bugbot were not tried: Cursor is not installed on the test machine, and their descriptions come from the official documentation. The BUGBOT.md blocks, the .mdc rule and the prompt are schemas to adapt.

Commenti
Caricamento commenti...
Sign in to comment