Troubleshooting#

Start with the smallest failing surface and keep the project read-only while diagnosing it.

Read the startup log first#

PacketBench validates its environment once at startup and writes the result to a daily log file:

The file is named packetbench.log.<date>. The startup check reports whether the data directory is writable, whether the operating system credential store answers, whether a trusted-projects file exists, and whether any PACKETBENCH_* environment variable is misspelled or points at a file that is not there. It never stops the application from opening, so a silent feature failure is usually explained by a warning in this file.

The desktop does not open#

Confirm the platform's Tauri prerequisites are installed, then run the source build from a terminal to capture the first error. Re-run pnpm install after a Node or lockfile change. Verify with pnpm build before retrying pnpm tauri dev.

Settings or workspaces are missing after an upgrade#

PacketBench mirrors its stored settings to ~/.packetbench/webview-storage-mirror.json and restores them before anything else loads, because the webview's own storage is scoped to the application's bundle identifier and starts empty when that identifier changes.

Open Settings → Security & Diagnostics → Trust & Diagnostics and read the Storage durability card. It reports whether the mirror is active, how many keys were restored on this launch, and what the legacy-prefix migration found. A mirror reported as inactive because it could not be read is the case worth acting on: the current session is running unprotected, so close the application, check that ~/.packetbench is writable, and reopen it.

A provider is unavailable#

Open provider Settings and refresh its status. Check the API key, endpoint and system clock. For Ollama, confirm the service is running and its model list is reachable. Remove temporary endpoint environment overrides. Verification is a short read-only conversation with a newly selected model.

Endpoints that carry a secret — the MiniMax URL, a custom OpenAI-compatible base URL and a Gitea, Forgejo or GitLab instance URL — are rejected when they use plain http:// towards a public host. Use https://, or keep the host on loopback, a private network address, a single-label hostname, or a .local, .lan, .internal or .home.arpa name. The Ollama URL is not covered by this rule because it carries no credential.

Background AI features produce nothing#

Session summaries, memory briefs and the other auxiliary AI tasks run in the background, at most two at a time, and a provider rate-limit response is retried twice before the task is abandoned. When the provider refuses every request, the feature stops producing output with nothing on screen.

Search the log for egress and read the response statuses. Repeated 429 responses mean the account behind the auxiliary provider is rate limited or out of quota — check the account before investigating anything else. A task that exhausts its retries logs a warning saying the turn was lost.

The sidecar is missing or incompatible#

From the source checkout run:

pnpm sidecar:install
pnpm sidecar:build

Remove developer path overrides unless you intentionally use a custom Node or sidecar entry. Restart PacketBench and confirm the sidecar status becomes ready.

A terminal pane closes immediately#

The pane now says how the session ended. A red bar with an exit code means the program itself failed; common codes are named in place, such as command not found, a required DLL was not found, or access violation — the CLI crashed on startup. An amber bar means the exit status could not be read, which is not itself evidence of a crash. Both bars stay until you use their Restart action. A grey [Session stopped] means PacketBench ended the session on your instruction.

If the pane fails before the program produces output, open Settings → Workspaces & Terminal → CLI Clients, select the CLI and use Test to resolve and run it exactly as a pane would. The card names which of the four resolution tiers supplied the binary: a Settings override, a legacy pin, PATH, or the product's own install directory. On Windows, an entry that resolves inside WindowsApps is an app-execution alias rather than an executable and is rejected; select the installed .exe explicitly.

Project hooks, MCP servers or sub-agents are ignored#

A project's own .claude/settings.json hooks, .mcp.json servers and .claude/agents definitions run only when that project is trusted. Trust is held in ~/.packetbench/trusted-projects.json:

{
  "version": 1,
  "projects": [
    "C:\\Users\\you\\projects\\your-app",
    "/home/you/projects/another-app"
  ]
}

Entries must be absolute paths that resolve on this machine, and trust is not inherited: a repository checked out inside a trusted directory is a separate project. A missing, unreadable or malformed file trusts nothing. Every skipped hook, server or agent definition is logged, so the log names what was ignored and which file it consulted.

Start a new conversation in that project after editing the file. The list is read each time PacketBench makes the decision, so no restart is required.

Sub-agents are additionally held to their declared tool list, and bash, write_file, edit_file and create_pull_request are removed from every sub-agent whatever its definition asks for. A dropped tool is logged by agent name.

GitHub agent tools report no token#

The GitHub token is read from the operating system credential store only. The former plaintext ~/.packetbench/github-token file is no longer read, and deleting it does not remove access. If the tools report a missing token, reconnect the GitHub account in Settings, and check the startup log for a credential-store warning.

SSH fails#

Test the same host with the system ssh client. Confirm hostname, user, port, key permissions and the saved fingerprint. Do not bypass a host-key mismatch. For remote agents, also verify Node.js, the remote sidecar and the absolute project path.

A Flight is stuck#

Inspect the attempt state for an approval request, process failure or target collision. Cancel before retrying. Preserve any useful commits, then verify worktrees with git worktree list from the target repository.

Collect a safe report#

Include the PacketBench version, operating system, failing surface and exact error, plus the relevant lines from the log file named above. For a CLI launch problem, Settings → Workspaces & Terminal → CLI Clients → Copy diagnostics produces a redacted report of each CLI's identifier, resolved path, tier and version, with home directories abbreviated.

Remove API keys, tokens, project secrets, home-directory names and remote host details before sharing logs.