Edit

Resume a Failed Build

Purpose: For platform engineers, recovers a build that crashed mid-step (usually a flaky download) without redoing the work that already succeeded.

The build orchestrator (src/opencenter_build/orchestrator.py:BuildOrchestrator) checkpoints every step into build/state.json. Re-running opencenter-airgap build reads that file and skips steps already marked completed.

Prerequisites

  • The build directory (build/) and its state.json from the failed run. If you deleted it, you cannot resume — start over.

  • config/versions.env and config/components.yaml unchanged since the failed run. Changing them invalidates the checkpoint hash and forces a clean run.

Inspect what failed

opencenter-airgap status

status prints the build ID, the config hash (a SHA of versions.env plus components.yaml), and the per-step table. Failed steps appear as ✗ Failed, with a truncated error message.

The full state is in build/state.json if you want the raw error:

jq '.steps[] | select(.status == "FAILED")' build/state.json

Resume

opencenter-airgap build

Resume is the default — --resume/--no-resume defaults to --resume. The orchestrator:

  1. Reads build/state.json.

  2. Compares the current config hash against the recorded one. If they differ, it refuses to resume and asks for --clean.

  3. Re-runs only the failed step plus any pending steps after it.

Force a clean run

If the state file is corrupted or you want to start over:

opencenter-airgap build --clean

--clean deletes build/state.json and reruns every step. It does not delete build/<repo>/ clones — re-cloning is expensive. To wipe everything, run opencenter-airgap clean first.

Force regeneration of the manifest

If you edited config/versions.env and want the new versions to flow into config/components.yaml, rerun the build. The orchestrator notices that versions.env is newer and merges new components into the existing manifest.

To discard manual edits and start from the version pins alone:

opencenter-airgap build --force-regenerate

--force-regenerate rebuilds config/components.yaml from versions.env and merges your custom additions on top — the merge logic in src/opencenter_build/component_manifest.py:merge_manifests() keeps additional images, charts, tools, and repositories that the generator did not produce.

Common resume failures

  • config hash mismatch — you changed versions.env or components.yaml between runs. Either revert the change or use --clean.

  • state file corrupted — invalid JSON. Delete it (rm build/state.json) and re-run.

  • step still failing — the underlying problem is real, not transient. Read the error in opencenter-airgap status and fix it before resuming. The ../reference/troubleshooting.md[Troubleshooting reference] covers the common build-time errors.

  • ../reference/build-steps.md[Build Steps] — what each step does and why it might fail.

  • ../reference/cli-commands.md#build[CLI Commands → build] — flag reference.

  • ../reference/cli-commands.md#status[CLI Commands → status] — output format.