|
| 1 | +# Troubleshooting — pi-coding-agent kit |
| 2 | + |
| 3 | +Failure modes specific to the pi-coding-agent kit, which installs |
| 4 | +[earendil-works/pi](https://github.com/earendil-works/pi) |
| 5 | +(`@earendil-works/pi-coding-agent`) via the npm registry at every sandbox |
| 6 | +start. Most diagnosis is done with `acq exec <sandbox> -- sh -c '…'`. Unlike |
| 7 | +the sibling `openchamber`/`paseo` kits, a bare `acq exec` here does **not** |
| 8 | +need any `PATH=` prepend to find `pi` — the install prefix is `$HOME/.local`, |
| 9 | +already first on the guest's default `PATH` (see |
| 10 | +[`docs/decisions/local-prefix-not-npm-global.md`](docs/decisions/local-prefix-not-npm-global.md)). |
| 11 | + |
| 12 | +## Node.js and/or npm not found |
| 13 | + |
| 14 | +**Symptoms:** the startup log shows |
| 15 | +`pi-coding-agent: node and/or npm not found on PATH; cannot install pi this |
| 16 | +boot (installing Node is out of scope for this kit — see spec.yaml)`, and `pi` |
| 17 | +never appears. |
| 18 | + |
| 19 | +**Cause.** This kit deliberately does not install Node — it assumes the base |
| 20 | +image already carries it (the same assumption `openchamber` makes for its own |
| 21 | +base image). A customized or minimal base image may not. |
| 22 | + |
| 23 | +**Fix:** use the `opencode` base template (the default, which ships Node), or |
| 24 | +add a Node install step ahead of this kit in your kit composition. |
| 25 | + |
| 26 | +## Node.js too old |
| 27 | + |
| 28 | +**Symptoms:** the startup log shows |
| 29 | +`pi-coding-agent: pi requires Node.js >=22.19.0, found vX.Y.Z; cannot install |
| 30 | +pi this boot (installing/upgrading Node is out of scope for this kit)`. |
| 31 | + |
| 32 | +**Cause.** pi's own published npm registry metadata (`engines.node`) requires |
| 33 | +Node `>=22.19.0`. npm's `engine-strict` defaults to `false`, so a plain |
| 34 | +`npm install` would otherwise proceed silently on an older Node and only fail |
| 35 | +later, opaquely, the first time `pi` itself runs — this kit checks explicitly |
| 36 | +up front instead, mirroring pi's own installer's preflight check. |
| 37 | + |
| 38 | +**Fix:** upgrade the base image's Node to `>=22.19.0`, or pair this kit with a |
| 39 | +Node-upgrade step. Confirm the guest's version: |
| 40 | + |
| 41 | +```bash |
| 42 | +acq exec <sandbox> -- sh -c 'node --version' |
| 43 | +``` |
| 44 | + |
| 45 | +## Malformed `PI_CODING_AGENT_VERSION` — install refused |
| 46 | + |
| 47 | +**Symptoms:** the startup log shows |
| 48 | +`pi-coding-agent: PI_CODING_AGENT_VERSION='<value>' doesn't look like a |
| 49 | +version; refusing to install` (or `... contains characters outside |
| 50 | +[0-9A-Za-z.-]; refusing to install`), and `pi` is never installed. |
| 51 | + |
| 52 | +**Cause.** The kit validates the version pin's shape before it ever reaches |
| 53 | +the npm package-spec string (`@earendil-works/pi-coding-agent@<version>`). |
| 54 | +This fails **closed**: an unexpected value (typo, stray whitespace, an |
| 55 | +accidentally-injected flag-looking token) is refused rather than silently |
| 56 | +passed through. Note that this is a defensive **format** check, not a |
| 57 | +security boundary on its own — the value is always passed as a single quoted |
| 58 | +argv word, never re-parsed by a shell, so it was never shell-injectable; the |
| 59 | +check exists so a malformed pin fails loudly and immediately instead of |
| 60 | +producing a confusing downstream npm error. |
| 61 | + |
| 62 | +**Fix:** set `PI_CODING_AGENT_VERSION` to either `latest` or a plain |
| 63 | +`MAJOR.MINOR.PATCH`-shaped string (matching `[0-9A-Za-z.-]` only) in the |
| 64 | +kit's `environment:`/spec configuration, then recreate the sandbox (or |
| 65 | +restart it so the startup step re-runs). |
| 66 | + |
| 67 | +## npm install failure or timeout |
| 68 | + |
| 69 | +**Symptoms:** the startup log shows |
| 70 | +`pi-coding-agent: npm install exited <rc> (prefix=...); pi unavailable this |
| 71 | +boot. See <log path>`, and `pi` is not on `PATH`. |
| 72 | + |
| 73 | +**Cause.** Most commonly: egress to `registry.npmjs.org` is blocked (this |
| 74 | +kit's only allow-listed host), a proxy/TLS issue (see the next entry), or a |
| 75 | +slow/silently-dropping connection. The install runs with |
| 76 | +`--fetch-timeout=30000 --fetch-retries=0` deliberately — this is a |
| 77 | +**startup-phase** script that runs on every boot, not a one-shot manual |
| 78 | +install, so retrying against a systemic failure just delays the sandbox for |
| 79 | +no benefit; the *next* boot retries naturally. |
| 80 | + |
| 81 | +**Fix:** check the install log and egress: |
| 82 | + |
| 83 | +```bash |
| 84 | +acq exec <sandbox> -- sh -c 'cat ~/.local/state/pi-coding-agent/install.log 2>/dev/null | tail -n 40' |
| 85 | +acq exec <sandbox> -- sh -c 'echo "${HTTPS_PROXY:-unset}"' |
| 86 | +``` |
| 87 | + |
| 88 | +If `registry.npmjs.org` is not reachable under org network policy, confirm it |
| 89 | +is on the sandbox's effective allow-list (`sbx policy log <sandbox>` / |
| 90 | +`acq policy log <sandbox>` under org governance may show it superseded). |
| 91 | + |
| 92 | +## CA-decode failure (malformed `PROXY_CA_CERT_B64`) |
| 93 | + |
| 94 | +**Symptoms:** the startup log shows |
| 95 | +`pi-coding-agent: PROXY_CA_CERT_B64 failed to base64-decode; proxy CA NOT |
| 96 | +added to the bundle (see <err path>)`, typically followed by an npm/TLS |
| 97 | +failure like `unable to get local issuer certificate` or |
| 98 | +`SELF_SIGNED_CERT_IN_CHAIN` on an inspected network. |
| 99 | + |
| 100 | +**Cause.** `PROXY_CA_CERT_B64` (base64-encoded PEM, supplied by whatever |
| 101 | +injects a proxy CA into the sandbox — e.g. the `zscaler-ca-certificate` kit) |
| 102 | +failed to decode. Unlike the sibling `openchamber` kit's equivalent block |
| 103 | +(which swallows this same decode failure via `2>/dev/null`), this kit's |
| 104 | +install script surfaces it explicitly, on the theory that a silently |
| 105 | +incomplete CA bundle produces a much more confusing downstream TLS error than |
| 106 | +telling you up front that the base64 itself was bad. |
| 107 | + |
| 108 | +**Fix:** confirm the value is actually valid base64-encoded PEM from the |
| 109 | +source that's supposed to provide it (commonly the `zscaler-ca-certificate` |
| 110 | +kit — pair it if you're on an inspected network), then recreate/restart the |
| 111 | +sandbox: |
| 112 | + |
| 113 | +```bash |
| 114 | +acq exec <sandbox> -- sh -c 'echo "PROXY_CA_CERT_B64 len=${#PROXY_CA_CERT_B64}"' |
| 115 | +acq exec <sandbox> -- sh -c 'echo "$PROXY_CA_CERT_B64" | base64 -d | head -c 40' # should start with -----BEGIN CERTIFICATE----- |
| 116 | +``` |
| 117 | + |
| 118 | +## pi installs but making an LLM-provider call fails TLS |
| 119 | + |
| 120 | +**Symptoms:** `pi` runs, but any call it makes to a model provider on an |
| 121 | +inspected network fails with a TLS trust error (`unable to get local issuer |
| 122 | +certificate`, `SELF_SIGNED_CERT_IN_CHAIN`). |
| 123 | + |
| 124 | +**Cause.** `NODE_EXTRA_CA_CERTS` only **appends** to Node's built-in trust |
| 125 | +roots — it needs the sandbox's proxy CA. Per the wrapper design in |
| 126 | +`docs/decisions/`, the CA bundle is **rebuilt once per boot** by the startup |
| 127 | +script, and the wrapper at `$HOME/.local/bin/pi` simply `exec`s the real `pi` |
| 128 | +binary with that boot's already-current bundle path — it does not rebuild |
| 129 | +anything itself at invocation. A plain `export` inside the install script's |
| 130 | +own process would not persist to a separately-launched `pi` process later, |
| 131 | +which is exactly why the wrapper exists. |
| 132 | + |
| 133 | +**Fix:** confirm the wrapper still references `NODE_EXTRA_CA_CERTS` and |
| 134 | +`exec`s the real binary (this is the normal, expected shape — not a sign of |
| 135 | +breakage): |
| 136 | + |
| 137 | +```bash |
| 138 | +acq exec <sandbox> -- sh -c 'cat ~/.local/bin/pi' # should show a small script that sets NODE_EXTRA_CA_CERTS and execs the real pi binary |
| 139 | +``` |
| 140 | + |
| 141 | +If the wrapper is missing `NODE_EXTRA_CA_CERTS` entirely (not just a static |
| 142 | +one-time export baked in at some earlier boot, but absent altogether), it has |
| 143 | +regressed; see `docs/decisions/` for the intended design and file an issue. |
| 144 | + |
| 145 | +## No model provider configured |
| 146 | + |
| 147 | +**Symptoms:** `pi` runs but has no LLM provider to talk to. |
| 148 | + |
| 149 | +**Cause.** This kit deliberately defers model-provider configuration (no |
| 150 | +USAi `models.json` catalog exists for pi yet — see the README's "Status" |
| 151 | +section). |
| 152 | + |
| 153 | +**Fix:** authenticate `pi` manually inside the sandbox — `/login`, a provider |
| 154 | +environment variable, or `~/.pi/agent/auth.json` — per |
| 155 | +[pi's own provider docs](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/providers.md). |
0 commit comments