Troubleshooting#

Most things that go wrong in PacketBench go wrong with an exact string attached — in a terminal pane, in an amber dictation panel, in a health badge, or in a sanitised host-API message. Those strings are the index into this page, because they are the only part of a failure a reader can search for.

This page groups symptoms by the surface that produced them, names the cause, and gives the workaround where one exists. Where a workaround cell reads —, there is none, and the row says why.

Terminal panes#

Everything below is what a PTY pane writes into its own xterm buffer. The pane never surfaces a modal for these; if you did not read the pane, you did not see the error.

The allowlist matches on the program name, not the whole command string (src-tauri/src/commands/pty.rs:66, :798). A manually pinned absolute path such as D:\projects\packetcode\bin\packetcode.exe is therefore accepted by its basename, which is the supported way to run a CLI that is installed somewhere PATH does not reach.

A silent pane end is not necessarily a clean exit#

A CLI that crashes on startup renders exactly like one you closed: the pane writes [Session ended] and stops. There is no exit code, no error, and nothing to act on.

The backend does the work and the frontend throws it away. commands/pty.rs reads the child's status and emits a typed PtyExitPayload; the normaliser for it, parsePtyExitPayload, is exported from src/lib/tauri.ts:227 and has no production callers — its only references are in tests. The real listener at src/hooks/useTerminalSession.ts:360 binds listen<unknown> and discards the payload. This is recorded as a P1 defect in backlog.md, not as a design decision.

The live case that found it: the vendored @openai/codex 0.147.0 binary access-violates on startup with 0xC0000005. On Windows a .cmd-wrapped CLI is spawned as cmd.exe /c codex.cmd (src-tauri/src/commands/pty.rs:873-880), so cmd.exe starts successfully, the PTY session is created, the real CLI dies milliseconds later, and the pane closes quietly.

Blank panes were a parser abort, not a missing feature#

xterm 6.0.0's bundled DECRQM handler (requestMode) throws ReferenceError: Can't find variable: i in minified builds, which aborts the entire parse. Any output stream containing a DECRQM query then renders nothing. opencode/opentui sends several on startup, which is why its panes were blank while claude and codex — which do not query — were fine.

PacketBench registers a no-op CSI handler for both DECRQM forms (src/hooks/useXterm.ts:68-69) so the broken built-in never runs. The CLI receives no mode-support reply and handles that gracefully. Implemented; if you still see a blank opencode pane on 0.13.1, it is not this.

SSH remote workspaces#

A remote workspace always launches ssh locally and runs the CLI on the other end, so failures split cleanly into local-spawn failures and remote-shell failures.

Dictation#

Dictation carries more failure machinery than any other surface, because a Bluetooth headset that walks out of range can block inside CPAL indefinitely and a bare spinner is a dead end.

The stall watch counts frames, not loudness — StallWatch::observe compares the cpal frame counter against the previous tick and never reads amplitude (src-tauri/src/commands/dictation/audio.rs:92-125). Speaking quietly does not trip it; a headset that goes silent without raising a stream error does, and so does a capture that never started at all, because the counter sits at zero from the first tick. It fires once per capture rather than once every 33 ms.

MCP servers#

Diagnose on a configured server spawns it, performs the MCP handshake, calls tools/list, and shuts it down. It reports one of four states, and those four are not four grades of the same thing. The last two rows are errors raised before any probe runs.

notProbed is not a failure#

The doctor is a local stdio prober by construction, and this build has no HTTP MCP client to probe with. An http or sse server therefore reports notProbed and carries no latency, because a number there would imply something was timed.

The distinction is load-bearing and is pinned by a test (src-tauri/src/commands/mcp.rs:604). Every non-stdio server used to be reported as degraded without a single byte being sent to it. degraded reads as "we checked and it is unhealthy", so every healthy remote server looked broken — which teaches you that the indicator means nothing and to ignore a real degraded when one appears. A malformed type is separated out for the same reason: it used to be swept into the same "remote, not probed" answer, which sent you looking for a network problem instead of a typo.

Git hosts#

Host API errors are sanitised before they reach you. The raw response body is logged, never displayed, because it can echo tokens and private repository data (src-tauri/src/core/git_host.rs:931).

<host> is resolved from the URL that actually answered: api.github.com becomes GitHub, any other host becomes its own hostname, and a hostless URL becomes Git host (src-tauri/src/core/git_host.rs:920-929).

Installers and first launch#

Nothing PacketBench ships is code signed. Every symptom in this table follows from that one fact — see Release status for what is and is not configured.

Related#

• Release status — why nothing is signed, and what has actually been proved on a packaged install.
• Install & first run — building from source, which is the path these symptoms assume.
• Workspaces & terminals — the pane, shell and session model behind the terminal table.
• SSH remote workspaces — host pinning, the remote PATH prefix, and what is gated off remotely.
• Dictation & analytics — capture, delivery safety, and the settings each timeout reads.
• MCP hub — trust profiles, and which agent rows can use a server at all.
• Where data lives — the files to inspect when a symptom looks like lost state.