Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions docs/box-operator.md
Original file line number Diff line number Diff line change
Expand Up @@ -269,6 +269,8 @@ started" from "the runner died in that early window".
| Exit 7 — `<wave> must be a whole number` | A decimal wave label (`9.1`), a non-numeric argument, or **no argument at all** — all three are usage errors, and all three exit 7. The verdict types `wave` as an integer | Pass the major number (`e2e-box.sh 9 main`). The check runs before the wheel build, so nothing was spent |
| Wheel build fails on the host | No build backend available | `pip install build` into the repo venv, or pass a prebuilt `BONFIRE_WHEEL` |
| Exit 3 — `no verdict emitted` | No `verdict.json` on disk: the container never started (bind-mount, image, daemon, OOM), or the runner died in its pre-trap window | Read the Docker log first — it says which. Then `docker run` with `-it` and re-execute the entrypoint to debug; pass `-e WAVE=<whole number>`, since a non-integer `WAVE` aborts the runner at exit 7 before its trap exists |
| FAIL, `artifact_manifest_missing` | No `artifact-under-test.json` in the run directory, so the runner has no wheel identity to check the mount against — the driver never built or never recorded one | Read the driver's host output; re-run `e2e-box.sh`, or pin a known wheel with `BONFIRE_WHEEL=/path/to.whl` |
| FAIL, `artifact_wheel_not_mounted:<wheel>` | The manifest names a wheel that is not in the read-only artifact mount — a bind-mount that did not take, or a run directory cleaned between build and launch | Check `.e2e-runs/<run>/artifact/` on the host and the `-v` flags in the docker run line; re-run rather than editing the mount |
| FAIL, `artifact_hash_mismatch` | The mounted wheel is not the one the driver built | Re-run; if it persists, something is rewriting `.e2e-runs/<run>/artifact/` |
| FAIL, `artifact_install_failed:artifact-and-deps` | Packaging drift — **the wheel itself** (or one of its requirements) does not install in a clean box. This step installs the artifact, not just its dependency set. The runner reached the wheel before it failed; a run that never reached the index is reported as `box_network_unreachable` instead | Read `pip-step-artifact-and-deps.log`, then `pip-install.log`. This is a real release blocker, not a box bug |
| FAIL, `box_network_unreachable:<step>` (runner exit 11) | The box could not reach its package index. pip already retried 8 times at a 60-second per-read timeout and still could not fetch. **The artifact was never installed, imported or executed, so this verdict says nothing about the wheel** | Read `pip-step-<step>.log` for the transport exception. Fix the host link and re-run; a warm `.e2e-runs/pip-cache/` means the retry does not re-download what already landed. Do not file this against Bonfire, and do not cite the run as evidence about the artifact either way |
Expand All @@ -293,6 +295,7 @@ started" from "the runner died in that early window".
| FAIL, `cost_log_present` | `.bonfire/costs.jsonl` missing or malformed | The writer honours `BONFIRE_COST_LEDGER_PATH`, so an empty target root means the run never charged or the export was lost — check `bonfire-artifact-inventory.txt` for a ledger under `~/.bonfire` before suspecting the run |
| FAIL, `review_verdict_emitted` | `.bonfire/review-verdict.json` missing or malformed | The reviewer stage writes it before posting to GitHub, so absence means that stage was never reached — read `bonfire-run.stdout` for where the run stopped |
| FAIL, `tampering_detected` | `gate/`, `tests/`, or `expected-assertions.yaml` changed | Cheat caught. File an issue with the model variant info |
| FAIL, `trap:sigterm` (143) / `trap:sigint` (130) / `trap:nonzero_exit` | The runner was **killed, not failed** — `docker stop`, a Ctrl-C on the host, or the OOM killer; the trap writes a FAIL verdict so a killed run is never silently lost. **These say nothing about the artifact** | Read the phase markers in the Docker log for where it was killed, check `dmesg` for the OOM killer, then re-run. Do not cite the run as evidence about the wheel either way |
| A PASS you don't trust | Run used the layer cache | Check `box-run.json::image.build_cache`. Re-run with `BOX_BUILD_CACHE=off` before citing it in a release decision |
| Docker daemon not running | systemd | `sudo systemctl start docker` |
| Fixture clone fails | No access to the private fixture, or an SSH-only remote configured | Verify HTTPS access (`gh auth status`), or point `FIXTURE_SRC_DIR` at a local checkout |
Expand Down
Loading
Loading