4. Exception handling

The four filters

The BREAKPOINTS view lists four exception filters. They are the coarse control, and for many projects they are enough.

A first-chance break passes the exception through correctly when you continue, so the debuggee’s own try/except still runs. You are looking at the raise, not preventing the handler.

The delphi filter can be narrowed to specific classes — a comma- or semicolon-separated allowlist such as EAccessViolation,EConvertError, empty meaning every Delphi raise. There is no launch.json field for this: unlike rules, filters are never configured from the launch configuration. Two ways to set it instead — the GUI pencil below, or an agent over MCP through the delphiExceptionClasses argument on launch_debuggee, attach_from_config or set_exception_filters (MCP).

VS Code exposes that same allowlist through the standard pencil icon it draws next to a filter row on hover — its own generic mechanism for a per-filter condition string, which this adapter wires up for the delphi filter only. It is not a second, competing rule language: typing there applies the same narrowing MCP’s delphiExceptionClasses does, just through the DAP setExceptionBreakpoints channel instead of a tool call. The rule engine below is the tool for anything past a flat class allowlist — per-unit, per-line, by message, or with an action other than break.

What you see on a stop

The debugger reads the exception object’s class name and its Exception.FMessage. For a native access violation with no Delphi object behind it, it synthesises a description instead — “Access violation at $RIP reading address $fault”.

The live exception object itself appears in Locals as a synthetic $exception row, shown as Class: Message and expandable like any other object. It works in Watch and hover too, so you can evaluate $exception.Message or drill into a custom exception class’s own fields.

That is the exception object at the instant it was raised. What happens once you are actually inside a handler — still stopped several lines later, on an ordinary breakpoint that has nothing to do with the exception itself — is its own thing, and it is deliberately different depending on whether the handler gave the exception a name.

Inside the handler: aliased vs. anonymous

on E: Exception do declares E as an ordinary local, scoped to that clause’s block — it shows up in Locals under whatever name you gave it, for as long as the stop is anywhere inside that block, not only at the moment of the raise. A bare except .. end with no on clause names nothing, so there is no local to show; instead the block gets its own $exception row, live for the same extent. The two are mutually exclusive by construction — a handler is never showing both at once, because a block is either aliased or it is not.

Both are ordinary operands past that point: E.Message = 'Test error' or $exception is EMyError work as breakpoint conditions exactly as well as they work in a watch or a hover, because they go through the same expression evaluator either way — typing $exception into Watch is a shortcut for the same lookup, not a separate mechanism. Stopped somewhere with no exception in scope at all, both report why rather than a bare parse error or an empty value.

Creating a rule without writing JSON

Filters are on/off per category. The moment a specific EFileNotFound in one unit is noise but the same class elsewhere is the bug you are chasing, you need a rule — and the fastest way to write one is to let the debugger do it, from the exception you are already looking at. Two commands, and you will use the second one far more often.

Create a Rule for This Exception…

Available only while stopped on an exception, from the floating debug toolbar.

It reads the exception in front of you and offers ready-made rules built from it — ignore this class everywhere, ignore it only in this unit, ignore only this exact raise site, log it with its stack instead of breaking, or match on a substring of its message. Pick one and it is written for you.

This is the answer to being interrupted for the third time by something the application handles perfectly well. The new rule is inserted first, which matters: first match wins, so it takes effect regardless of what is already in the list.

Edit Exception Rules…

From the title bar of the Breakpoints or Call Stack view — those icons appear when the mouse is over the view. It works with no session running, which is how you edit the shared rules file on its own.

It first asks where the rules should live — see where rules live for the three files behind this and how they rank. Each option shows how many rules it currently holds; a file that does not exist yet says so instead of a count, since saving there creates it. If there is only one possible target the question is skipped.

Then the editor itself, one card per rule:

• A plain-language summary of what the rule does, rewritten as you type — class = EAbort AND unit OracleData → ignore, or any exception → break when you have not filled anything in.
• The nine criteria as labelled fields, each with a hint explaining what it matches, and the action as a dropdown whose help text changes with the selection.
• Buttons to move the rule up or down — which is what changes the outcome, since evaluation stops at the first match — plus duplicate and delete. Delete asks nothing, so be deliberate.
• Validation on every keystroke. A malformed regular expression, a line range whose end precedes its start, a missing action, a field name that is not one of the nine — all are listed at the bottom, and the save button stays disabled until they are fixed.

The rule engine underneath

Both editors above write into whichever of the three files you picked — where rules live covers exactly which files those are and in what order they rank. Inside any of them a rule is a flat JSON object: any number of optional criteria, plus a required action. Knowing the shape is what lets you hand-edit a file faster than reopening the GUI for a one-word change, or write a rule the editor cannot express yet.

Each file is either a bare array of rules, or an object with an exceptionRules key holding the same array — the editor preserves whichever shape it finds:

[
  { "class": "EAbort", "action": "ignore" },
  { "messageRegex": "ORA-\\d+", "action": "logStack" },
  { "class": "EAccessViolation", "unit": "OracleData",
    "lineFrom": 2700, "lineTo": 2800, "action": "break" }
]

Criteria present in a rule are AND-ed; criteria you omit are wildcards. Evaluation is first match wins, top to bottom.

Criteria

Actions

Where the criteria come from

unit, line and the line range refer to the raise site — the first stack frame with known source — not to the address the OS reported the exception at. Using them makes the adapter walk the stack on every exception, which is a real cost with the all filter switched on.

Two consequences worth knowing before you write rules against them. unit: "*unknown*" means there is no raise site, so any line criteria on that same rule can never be evaluated. And because line seeds both bounds before lineFrom / lineTo are applied, { "line": 100, "lineTo": 200 } means the range 100 to 200, not line 100.

class also matches the synthesised names the debugger uses for exceptions with no Delphi object — EAccessViolation for an access violation, and Exception 0x… forms for other native codes.

One exception can never be matched by a rule: TThread.NameThreadForDebugging raises code 0x406D1388 purely to announce a thread name, and the debugger consumes it before any filter or rule runs. It never surfaces as a stop; the name shows up on the thread’s row in the Call Stack instead.

Where rules live

Rules come from up to three files, tried in this order — narrowest scope first, first match wins across the whole chain:

There is no launch.json field for rules — that used to exist and was removed on purpose. “Debug X” and “Attach to X” are the same program started two different ways, and a rule that applied only through one of them was a trap disguised as a feature: nothing about how you connected the debugger has anything to do with which exceptions matter. If a launch configuration still carries an exceptionRules array from before this changed, it is simply not read any more.

Tiers 1 and 2 exist only when a launch or attach configuration names the Delphi project it debugs, through delphiProjectFile — the .dpr, .dpk or (what RAD Studio’s own project services actually report) .dproj path, written automatically by the IDE plugin and resolved by VS Code before the adapter ever sees it. All three spellings of a project name the same pair of files: the adapter derives them from the path’s directory and base name, so Debugme.dproj and Debugme.dpr both point at Debugme.ExceptionSettings.json. This is the scope a Delphi developer actually works in — a .dpk loaded by a host that hosts dozens of other packages carries its own rules, wherever it is loaded from and whoever launched the host.

Turn tier 3 off per configuration with "useGlobalExceptionRules": false, or point it somewhere else with globalExceptionRulesPath.

All three are re-read on every resume: edit any of them while stopped, continue, and the new rules apply without restarting the session. That is worth using deliberately — when something keeps interrupting you, edit the file, press F5, and it is gone, without losing the state you spent twenty minutes reproducing. This even covers creating a sidecar file that did not exist yet mid-session — the adapter notices the file appear, not just change.

Two things that will bite

A catch-all rule in a narrower tier hides everything below it. The three files are evaluated as one ordered list, tier 1 through tier 3 — so a rule with no criteria at all in the local file makes the shared and machine-wide files unreachable, and one in the shared file does the same to the machine-wide file. If a rule you know is in a wider-scoped file stopped firing, look for a catch-all above it first.

A rule with a bad code is dropped, not widened. If the exception code will not parse, the whole rule is discarded rather than treated as “matches any code” — which would silently turn a narrow rule into a catch-all that swallows everything below it. Nothing is reported in the Debug Console, so if a rule seems to have no effect, check its code spelling.

log and logStack write to the Debug Console, not to the debugger’s diagnostics channel. That is the right place — it is your program’s behaviour being reported, not the debugger’s — but it means a noisy log rule shares the pane with your program’s own output.

Stepping out of an exception

Step over, into and out all work while stopped on an exception, and run to the nearest enclosing handler. The debugger finds that handler by deriving it from the binary itself and setting a one-shot breakpoint there — it does not guess.

Where the handler address cannot be proven — which is the case for every try/finally, and for every bare except on a 32-bit target — the step is refused with a stated reason instead. That is deliberate. A guessed handler address would resume the program somewhere arbitrary, and you would have no way to tell.