Troubleshooting#

Start with packetcode doctor. It reports the data home, provider readiness and a config.validation check that names any setting that will fail or do nothing — a missing env_from variable, an api_key_env naming an unset variable, a custom provider with an unusable base_url, an enabled MCP server with no command, an out-of-range [behavior] value, or a default provider with no key. PacketCode prints the same list to standard error at startup, each line prefixed with the command that printed it: packetcode: config, packetcode run: config or packetcode acp: config. Validation is reported, never fatal, so treat an item as a setting to correct rather than a crash to reproduce.

Collect a diagnostic log#

Set PACKETCODE_LOG_FILE to an absolute path before starting PacketCode. Each run then appends one JSON object per line to that file, which is created with mode 0600. The log is off when the variable is unset.

PACKETCODE_LOG_FILE="$HOME/packetcode-diagnostics.jsonl" packetcode

Recorded events cover startup, every provider HTTP attempt (method, URL without its query string, attempt number, status or transport error, elapsed milliseconds), Codex token refresh, the policy decision and approval answer for each tool call, ACP session and permission activity, MCP server spawns, fetch requests, SSH connections, hook runs and sugar login.

Request and response bodies, headers, tool arguments, prompt text, API keys and tokens are never written, and provider query strings are stripped even from transport error text. The fetch event is the exception: it records the URL the model requested, including its query string, because that URL is the evidence.

Warning: keep the log on protected storage and read it before attaching it to a report or sharing it.

PacketCode is not found#

Run the binary by its full installed path. If that works, add the containing directory to PATH and open a new terminal. Verify with packetcode --version.

A source build fails on the Go version#

PacketCode requires Go 1.26.0 or newer. With the default GOTOOLCHAIN=auto, an older Go fetches a compliant toolchain automatically. A build pinned to GOTOOLCHAIN=local on an older toolchain fails instead; install Go 1.26 or newer, or unset the pin. See Install.

First-run setup or provider authentication fails#

Run packetcode doctor. Check the selected provider slug, model, API-key environment variable and endpoint. For Codex, verify the Codex CLI is signed in. For Ollama, verify the local service and model are available. Start a new read-only session after correcting configuration.

The interface renders incorrectly#

Use a terminal with modern colour and keyboard support, reset custom theme or statusline configuration, and retest without a terminal multiplexer. Compare with a plain local terminal before reporting a rendering defect.

A command or edit did not run#

Inspect the permission decision and ordered deny rules. An ask result requires an explicit approval; a deny result cannot be overridden by proceeding in the conversation. Confirm the requested tool name, and confirm the rule's command_prefix is written from plain command words rather than options — a prefix carrying an option of its own matches nothing.

A command that reaches a denied program indirectly — through sh -c, sudo, xargs or a scripting interpreter — or whose match cannot be settled from the command string alone becomes an approval prompt rather than an allow. That is the deny floor working, not a rule failing to match. See Permissions.

A file read is refused#

read_file refuses .env and any .env.<suffix> file and says so, because PacketCode reads provider credentials from those files itself. search_codebase omits them from results and an @-mention of one expands to nothing. The example spellings .env.example, .env.sample, .env.template and .env.dist remain readable, although a ripgrep-backed search excludes them too. Copy the values you genuinely need into a non-secret file.

A tool result says output was withheld#

Large tool results are capped where they enter the conversation. The model receives the beginning and end of the output, the number of bytes withheld and, in the usual case, a handle that retrieves the remainder. Handles belong to one session and are released when it ends; a handle from an ended or pruned session reports that the output is no longer retained.

Retention is not guaranteed. A single result larger than the session's whole retained-output budget is not kept at all, and an earlier result can be dropped once later ones fill that budget. The marker then says the omitted bytes were not retained and cannot be retrieved. Re-run the tool to regenerate the output.

An MCP server does not start#

Run its configured command directly, verify the executable and arguments, then check that the process uses stdio rather than an unsupported transport. Disable the server until it starts predictably outside PacketCode.

A clean exit is reported as a clean exit. If quitting still reports mcp: server exited: read |0: file already closed for a server that stopped normally, check packetcode --version and upgrade.

An ACP client is refused a session#

A client that reads a prompt response and immediately sends session/load is served. If the client reports session already has an active prompt when switching sessions, check packetcode --version and upgrade.

packetcode acp writes configuration, .env and validation problems to standard error at startup; standard output carries only the protocol stream, so capture the two separately when diagnosing a client.

A background agent or workflow is stuck#

Cancel before retrying. Inspect its job record, process output and worktree. Preserve any commits, then verify with git worktree list. Do not assume a record marked incomplete means no files changed.

Approvals are queued per request, foreground first, so cancelling one job no longer leaves its prompt on screen blocking every other job. If an old build shows a prompt for a job that has already ended, restart PacketCode and upgrade.

Remote work fails#

Test with the system ssh client. Confirm the pinned host key, user, project root and remote dependencies. Never bypass an unexpected host-key change.

Windows quoting or job records misbehave#

Quotes in a command are passed to cmd.exe verbatim, so the documented PowerShell form runs as written. A job record briefly locked by a concurrent read is retried rather than reported as malformed. If you see escaped quotes in command output, or a job that vanishes from the list and reloads as unreadable, check packetcode --version and upgrade.

When reporting a problem, include the version, OS, terminal, provider slug and exact error. Remove keys, tokens, prompt content and private paths.