14.8. Breakpoints
Prev | Chapter 14. Lua Debugger | Next

## 14.8. Breakpoints

The Breakpoints section lists every breakpoint the debugger knows about, with three columns:

- Active — a checkbox. Unchecking disables the breakpoint without removing it.

- Hits — a compact summary of the row’s hit-count gate plus the running counter, so you can see at a glance "what kind of pause is armed and how close it is to firing" without hovering the row tooltip. The cell uses a tiny grammar that mirrors the inline editor’s mode dropdown:

  - `≥N` — `from` mode: pause from the N-th hit onwards.
  - `×N` — `every` mode: pause on hits N, 2N, 3N, ….
  - `@N` — `once` mode: pause once on the N-th hit, then deactivate the row.
  - The cell starts with the running hit counter; if a gate is set it follows in parentheses, e.g. `3 (≥10)` means "currently at 3 hits, armed at ≥10". With no hit gate the cell is just the counter.
  - Hover the column header to see the same grammar in tooltip form. To set or change the gate, edit the Location cell — see Section 14.8.2, “Conditions, hit counts, and logpoints”.
- Location — `source:line` for the line of the breakpoint.

Rows whose source file no longer exists on disk are drawn with a warning icon, gray text in every cell (including Hits), and a disabled Active checkbox; their tooltip reads File not found: <path> so you can spot stale entries that the loader will never resolve.

Alongside line breakpoints, the debugger can also pause on any Lua runtime error — see Section 14.8.1, “Break on Error”.

Breakpoints are created and removed in several ways:

- Click the gutter of the editor next to a line to toggle a breakpoint. A red circle appears in the gutter for active breakpoints; an inactive breakpoint is drawn as a gray circle. `Shift`-clicking the gutter on an existing breakpoint toggles only its active state (red ↔ gray) without removing it; on a line with no breakpoint, `Shift`-click adds a disabled (gray) breakpoint, which is handy for pre-arming a line you want to break on later without paying the line-hook cost until you activate it. The gutter’s tooltip surfaces both behaviors.
- Use the editor context menu: Add Breakpoint / Remove Breakpoint on the line under the cursor, or with the script editor focused use `Ctrl+Shift+B` to toggle a breakpoint on the current line (same as the context-menu shortcuts).
- Run to this line (toolbar, editor context menu; only while paused) sets a one-shot target on that line and resumes; with the script editor focused, `Ctrl+F10` does the same. The target clears itself the first time execution reaches it, and is also discarded by Continue or any Step. The target survives across dissector returns, so a line that is only reached on a later packet still pauses.

Looking for conditional breakpoints, hit counts, or logpoints? Edit the Location cell of a breakpoint row to attach any of those — see Section 14.8.2, “Conditions, hit counts, and logpoints”.

Double-clicking a row in the Breakpoints table opens the corresponding file in the editor and jumps to the line.

The section header carries five small controls to the right of the title rule, in left-to-right order:

- `⚠` — Break on Error toggle. Gray when off, red when on. Click to flip; the setting is remembered across Wireshark restarts. See Section 14.8.1, “Break on Error”.
- a colored dot — the aggregate-active toggle. The dot mirrors the gutter convention: gray when every breakpoint is inactive, red when any breakpoint is active. Clicking it flips the aggregate state in one shot — gray → activates every breakpoint, red → deactivates every breakpoint. The control is disabled (and the dot stays gray) when there are no breakpoints. Its tooltip describes the click outcome and reminds you of the per-line `Ctrl+Shift+B` shortcut.
- `－` — Remove Breakpoint (`Delete`). Removes the selected rows; disabled when nothing is selected.
- `⚙` — Edit Breakpoint. Opens the inline editor on the focused row (or the first selected row), the same as double-clicking the Location cell or pressing `F2`.
- `Ⓧ` — Remove All Breakpoints (`Ctrl+Shift+F9`). Disabled when the Breakpoints list is empty.

The Breakpoints table supports `Ctrl` / `Shift` click for multi-row selection. A right-click context menu groups its entries by scope — first the actions that target the row under the cursor, then the actions that target the whole table:

- Edit…​ — opens the inline editor on the clicked row, same as double-clicking Location or pressing `F2`. Disabled on stale rows whose target file is no longer loaded.
- Open Source — jumps the editor to the breakpoint’s file and line. Double-clicking Location also navigates here, in addition to opening the inline editor.
- Reset Hit Count — clears `hit_count` and the `{delta}` reference timestamp for the clicked row. Enabled when the row has a hit-count target or a counter greater than zero.
- Remove — drops the selected rows (`Delete` / `Backspace` also work).
- Reset All Hit Counts — clears `hit_count` and the `{delta}` reference timestamp on every row that currently has a non-zero counter.
- Remove All Breakpoints — drops the whole list, same as the `Ⓧ` control in the section header (labeled with `Ctrl+Shift+F9` in the menu; the shortcut works from anywhere in the dialog).

Breakpoints survive Wireshark restarts. Adding a breakpoint automatically turns the debugger on if it was off — running with no line hook cannot trigger a pause.

### 14.8.1. Break on Error

In addition to line breakpoints, the debugger can pause whenever your Lua code raises a runtime error — a failing `assert`, an explicit `error("…​")`, or an unhandled error such as `attempt to index a nil value`. Break on Error is a single switch that applies to every Lua callback the debugger sees; nothing is attached per script or per line.

Toggle it from the Breakpoints section header. The setting is remembered across Wireshark restarts. Turning the button on automatically enables the debugger if it was off — a pause cannot fire while the line hook is not installed.

When Lua raises an error and Break on Error is on, the debugger pauses on the failing line. The pause behaves like a regular breakpoint: the editor jumps to that line, Variables, Watch, and Stack Trace repopulate against the paused frame, and the rest of Wireshark grays out (see Section 14.2, “Pause Behavior”). An inline bar under the editor shows the error message.

Live-capture suppression still applies: while a live capture is running the debugger is forcibly off, so Break on Error does not fire (see Section 14.2.1, “Live-capture suppression”). To debug an error you can only reproduce on live traffic, save the capture and reload it offline.

### 14.8.2. Conditions, hit counts, and logpoints

The Location cell of a breakpoint row is editable (double-click, `F2`, or right-click → Edit) and lets you attach one of three extras to the breakpoint. A white core inside the breakpoint dot — in the Breakpoints list and in the editor gutter — marks rows that carry an extra:

- Expression — a Lua expression evaluated each time control reaches the line. The breakpoint pauses only when the expression is truthy in the current frame; locals, upvalues, and globals are visible exactly as they are in Watch / Evaluate. Runtime errors are treated as false (no pause) and surface as a warning icon on the row.

- Hit Count — gate the pause on a hit-counter. `0` disables the gate. A small dropdown next to the integer picks the comparison mode:

  `from` | Pause on every hit from N onwards — inclusive of the N-th hit (default; "skip the first N-1, then pause forever").
  `every` | Pause on hits N, 2N, 3N, … — sample a noisy loop without stopping on every iteration.
  `once` | One-shot. Pause on the N-th hit and deactivate the breakpoint so subsequent hits go through. The slot is consumed the moment the counter reaches N, even if the row’s Expression evaluates falsy or the row is a logpoint that emits and resumes — the row deactivates either way. The row’s Active checkbox visibly clears AND the runtime counter resets to zero in the same step, so re-ticking Active is enough to arm the next N-hit cycle without a separate Reset Hit Count.

  The counter is per breakpoint and is not persisted across Wireshark restarts.

- Log Message — a template that is written to the Evaluate output (and to Wireshark’s debug log) each time the breakpoint fires — that is, after the Hit Count gate and any Expression allow it. By default execution continues without pausing; click the pause toggle on the editor row (the icon next to the Log Message field) to also pause after emitting (useful for "log-then-inspect" without duplicating the breakpoint). The line is emitted verbatim — there is no automatic file:line prefix; include the origin via the tags below if you want it.

The Log Message template uses `{…​}` placeholders. `{{` and `}}` produce literal `{` / `}`. Anything inside `{}` that is not one of the reserved tags below is evaluated as a Lua expression in the paused frame and converted to text with the same coercion `tostring()` performs; per-placeholder evaluation errors substitute `<error: …​>` without aborting the line.

The reserved tags below shadow any same-named Lua local / upvalue / global. To log a Lua variable that happens to share a name with a tag, wrap it: `{tostring(filename)}`.

Origin

`{filename}` | Source file path (canonicalized).
`{basename}` | Last path component of `{filename}`, e.g. `printer.lua`. Empty when the chunk has no on-disk path.
`{line}` | 1-based line number of the breakpoint.
`{function}` | Running function’s name (`debug.getinfo` `n`), or `?` for anonymous, tail, and main-chunk frames.
`{what}` | Frame kind: `Lua`, `C`, `main`, or `tail`.

Counters and scope

`{hits}` | This breakpoint’s cumulative hit counter — the number of times the line has been reached since the row was created or the counter was last reset. The counter advances on every line hit, including hits skipped by the hit-count gate or a falsy Expression; the log line itself only emits on hits the gates pass, so the value rendered is the counter at the firing moment (e.g. `every 100` shows `100, 200, 300, …`).
`{depth}` | Lua-frame stack depth at the fire site.
`{thread}` | `main` for the main thread, `coro@<ptr>` for coroutines (the pointer is stable per coroutine within a session).

Time

`{timestamp}` | Local wall-clock `HH:MM:SS.mmm` at fire time.
`{datetime}` | Local `YYYY-MM-DD HH:MM:SS.mmm` at fire time.
`{epoch}` | Unix time, seconds with millisecond fraction.
`{epoch_ms}` | Unix time as integer milliseconds.
`{elapsed}` | Milliseconds since the debugger was last attached.
`{delta}` | Milliseconds since this breakpoint last fired (`0` on the first fire and after Reset Hit Count / Reset All Hit Counts).

#### 14.8.2.1. Examples

The mini-blocks below resolve against the names defined by the `printer.lua` postdissector in Section 14.3, “Getting Started”: locals `tvb`, `pinfo`, `tree`, `offset` inside `printer.dissector`, upvalues `sessions`, `last_seen`, `opcode_names`, `handshake`, `ip_src_F`, `tcp_flags_F`. Drop a breakpoint on any line of `printer.dissector` and edit its Location cell to attach the extras shown.

Expression — gate the pause on a Lua predicate.

    -- Pause only after frame 100:
    pinfo.number > 100

    -- Only on the first dissection of a frame:
    not pinfo.visited

    -- Only TLS in either direction:
    pinfo.dst_port == 443 or pinfo.src_port == 443

    -- Frames whose IP source we have seen before:
    last_seen[tostring(pinfo.src)] ~= nil

    -- Bail-out invariant: pause if a length assumption breaks:
    tvb:len() < 20

A runtime error inside the expression is treated as `false` and shows a warning icon on the row, so a typo or a `nil` index silently disables the pause instead of stopping execution. See Section 14.6.3, “Expression patterns” for the full menu of shapes the same evaluator accepts.

Hit Count — gate the pause on a counter.

The integer field carries N; the dropdown next to it picks the comparison mode. The block below sketches the three shapes the gate can take (each line reads as "mode N" — the mode is the dropdown selection, N is what you type into the integer field):

    from 10   -- ignore the first 9 hits, pause from hit 10 on
                 (default mode; "skip the warm-up")
    every 100 -- sample a tight per-packet loop: pause on hits
                 100, 200, 300, …
    once 5    -- one-shot debug: pause on hit 5 and clear the
                 row's Active checkbox; tick it again to re-arm
    0         -- disable the gate (any mode); same as clearing
                 the field

The counter is per breakpoint and per Wireshark session. It is preserved across edits to the Expression, the Hit Count target or mode, and the Log Message — tuning the threshold or switching from `from` to `every` mid-run will not throw away the count you were watching, with one exception: lowering the target below the current counter rolls the counter back to `0` so the breakpoint can resume waiting for "the next N hits" instead of pausing on every line. Right-click the row and choose Reset Hit Count — or Reset All Hit Counts on the empty area of the table — to zero it explicitly. The counter is not persisted across Wireshark restarts. Hit Count, Expression, and Log Message on the same row run in a strict order: hit-count → Expression → Log Message. The hit-count gate runs first; only when it passes is the Expression evaluated; only when the Expression is truthy (or absent) does the Log Message emit and the row pause. So a logpoint with a condition stays silent while the condition is false, and an `every 100` logpoint with `tvb:len() > 1500` only logs on the matching every-hundredth packet.

Log Message — show where the line hit.

    {filename}:{line}
    {basename}:{line} in {function}
    {filename}:{line} ({what}) hits={hits} depth={depth}
    [{thread}] {function}:{line}

`{basename}` is the readable form of `{filename}` — the script’s filename without its directory, useful when most logs come from one or two scripts and the absolute path is just noise. `{function}` is `?` for anonymous, tail, and main-chunk frames; `{what}` (`Lua` / `C` / `main` / `tail`) disambiguates them. `{thread}` is `main` for the main coroutine and `coro@<ptr>` otherwise — handy when a dissector is called from a tap callback that runs on its own coroutine.

Log Message — wall-clock and intervals.

    [{timestamp}] hit
    [{datetime}] entered {function}
    {epoch_ms} -- frame seen, ms since the Unix epoch
    {elapsed} ms since the debugger was attached
    loop iteration {hits} took {delta} ms since the previous fire

Use `{timestamp}` for short interactive sessions and `{datetime}` for long-running captures where you may cross midnight. `{delta}` reports `0` on the very first fire (and after Reset Hit Count / Reset All Hit Counts), so a "took 0 ms" line in the log marks a fresh counter rather than an instant fire.

Log Message — mixing tags with Lua expressions.

Anything inside `{}` that isn’t a reserved tag is evaluated as a Lua expression in the paused frame and converted to text with the same coercion `tostring()` performs, just like a Watch row.

    frame {pinfo.number}: {tostring(pinfo.src)} -> {tostring(pinfo.dst)}
    bytes_left={tvb:len() - offset} at {filename}:{line}
    flags=0x{string.format("%02x", tvb:range(13, 1):uint())}
    {tostring(pinfo.src)} last seen at frame {last_seen[tostring(pinfo.src)] or "never"}
    {datetime} hit #{hits}: ports {pinfo.src_port}->{pinfo.dst_port}

Wireshark userdata classes (`Address`, `Pinfo`, `Tvb`, …) expose their canonical text via `__tostring`, so wrap them in `tostring(…​)` instead of relying on a `:tostring()` method (the class doesn’t have one). `{` is the only character that needs escaping; `{{` and `}}` produce literal braces:

    state = {{ src={tostring(pinfo.src)}, dst={tostring(pinfo.dst)} }}

A per-placeholder runtime error becomes `<error: …>` inline, so one bad expression in a long template doesn’t drop the rest of the line. Edit the row’s Location cell to clear the bad placeholder.

| Logpoints on every packet of a large capture
A logpoint that matches every packet of a multi-thousand-frame capture can fire thousands of times per second. The debugger coalesces those fires onto the GUI thread in a single drain per event-loop tick, and the Evaluate output keeps only the last ~5000 lines (older lines are evicted as new ones arrive), so the dialog stays responsive — but each fire still runs the template formatter on the Lua thread. To keep per-packet logpoints cheap on big captures: Throttle with Hit Count: pick `every` N (e.g. `every 100`) to sample one out of every N matches instead of all of them. Filter with Expression: a predicate like `pinfo.dst_port == 443` or `tvb:len() > 1500` skips the format-and-emit path entirely on every non-matching frame. Keep templates lean: `{depth}` walks the Lua call stack and `{thread}` queries the running coroutine on every fire. Tags the template doesn’t reference are skipped, so omit ones you don’t need.

Prev | Up | Next
14.7. Stack Trace | Home | 14.9. Files