Skip to content

[Improve] Structured boot error codes and Docker spawn preflight - #622

Merged
daniel-lxs merged 2 commits into
developfrom
feat/boot-failure-error-codes
Jul 20, 2026
Merged

[Improve] Structured boot error codes and Docker spawn preflight#622
daniel-lxs merged 2 commits into
developfrom
feat/boot-failure-error-codes

Conversation

@daniel-lxs

Copy link
Copy Markdown
Member

What changed

Follow-up to #544, which mapped Docker boot failures to friendly copy by pattern-matching error prose. This PR makes boot failures first-class instead:

  • Preflight before any sandbox resources are created: the Docker provider now checks that the daemon responds and that the worker image is available locally (pulling explicitly when a registry hosts it). The most common self-host failures now fail instantly with a precise reason instead of after a 60s start wait.
  • Machine-readable error_code on task_runs (additive column): the controller raises DockerBootError at the sites that know the category (preflight, release-archive checks, worker start assertions with fetch failed log classification), with a controller-side regex classifier as fallback for untyped docker failures.
  • The web startup UI maps the persisted code to copy directly; text inference remains only for runs that failed before codes existed. Unknown codes from newer/older releases are ignored safely.
  • Drift telemetry: a docker spawn failure that matches no category logs a warning, so the classifiers can't silently rot.
  • Docs: the Docker sandbox provider page now maps each boot-failure message to its fix.

Why this change was made

#544 explained failures after the fact by reverse-engineering prose with seven regexes — brittle against Docker error-string drift, and invisible in telemetry. The controller knows which failure happened at throw time; persisting that category makes failure classes countable and the UI mapping exact. Preflight converts boot-then-fail into fail-fast for the cases operators hit most (daemon down, missing image).

Impact

  • Self-host boot failures surface instantly with precise, actionable copy.
  • Failure categories are now queryable (task_runs.error_code) for support and telemetry.
  • Schema change is additive only (N-1 rollback safe).
  • Old failed runs keep working via the text-inference fallback.

Validation

  • 74 controller + 10 web + 54 sdk finish-run tests pass, including new coverage for preflight, classification, code persistence, and code-preferred display mapping
  • pnpm lint:fast, pnpm check-types:fast, pnpm knip all green

🤖 Generated with Claude Code

Boot/spawn failures now persist a machine-readable error_code on
task_runs (additive column). The controller raises DockerBootError at
the sites that know the category — a new preflight (daemon reachable,
worker image present with explicit pull) plus the release-archive and
worker-start assertions — with a regex fallback classifier as the
single source of truth for untyped docker failures. The web startup UI
maps the persisted code to copy directly, keeping text inference only
for runs that predate codes, and logs a drift warning when a docker
failure matches no category.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@roomote-roomote

roomote-roomote Bot commented Jul 20, 2026

Copy link
Copy Markdown
Contributor

No code issues found. See task

  • apps/web/src/lib/task-run-errors.ts:117 Unknown persisted codes such as toString pass the in check through Object.prototype, yielding a function instead of display copy; the subsequent friendly.includes(...) call throws and crashes the failure UI. Use an own-property check so unknown codes fall back safely.

Reviewed d002a8c

Review finding: `in` walks the prototype chain, so a junk persisted
code like "toString" resolved to a function and crashed the failure UI.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@daniel-lxs
daniel-lxs merged commit dc6c4f1 into develop Jul 20, 2026
16 checks passed
@daniel-lxs
daniel-lxs deleted the feat/boot-failure-error-codes branch July 20, 2026 17:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant