Troubleshooting

Troubleshooting

cmd/oci-builder

Message / symptom	Cause	Fix
binary is not executable	the file has no execute bit	chmod 0755 service, then rebuild with CGO_ENABLED=0
binary must be a regular file	you pointed -binary at a directory, symlink, or special file	pass a real, regular executable file
unsupported architecture "X" (supported: amd64, arm64)	-arch was something else	pass -arch amd64 or -arch arm64, and build the binary for that same target
output already exists: ...	-output already exists (files are never overwritten, intentionally)	choose a new output path
entrypoint must be an absolute, clean container path	-entrypoint wasn't absolute, wasn't path.Clean-stable, or was exactly /	use something like /app/service
invalid label "X" (expected key=value)	a -label had no =, or an empty key	fix the key=value pair
duplicate label "X"	the same label key was passed twice	remove the duplicate; the builder refuses to guess which value should win
CI rejects the binary before building anything	scripts/ci/verify-elf.sh found a PT_INTERP header (dynamic linking) or a wrong-architecture ELF	rebuild with CGO_ENABLED=0 GOOS=linux GOARCH=<arch>

Full flag reference: CLI Reference.

Registry / release

Symptom	Fix
Registry publication fails in ci-release.yml	use the workflow's own artifacts instead of retrying blindly; confirm the repository's Actions permissions actually allow packages: write before retrying
Can't tell if a pulled image matches what was validated	pull by digest, not tag, and cross-check against release-reports/verified-layout.tar / signature-verification.json from the release's evidence bundle - see Testing and CI/CD

Dockerfile / local Podman build

Symptom	Fix
docker build/podman build fails in the verify stage	the layout at ./oci-image failed one of the sanity checks (missing marker file, wrong blob count, digest mismatch) - re-run python3 scripts/ci/verify-oci-layout.py ./oci-image standalone for a precise reason
docker exec/podman exec -it ... sh doesn't work	the final image is FROM scratch - there is no shell by design; see Debugging Minimal Containers
Service unreachable after docker run/podman run	check you actually published the port (--publish 8080:8080) and that the entrypoint is listening on 0.0.0.0, not just 127.0.0.1, inside the container

MicroVM

Symptom	Fix
scripts/microvm/check-kvm.sh fails on /dev/kvm	see the 4-step install procedure in MicroVM Support
OCI_VALIDATION_FAILURE: ... from run-microvm.sh	the directory you pointed it at isn't a genuine, structurally-valid cmd/oci-builder layout (or was tampered with) - run-microvm.sh refuses to boot it by design (see MicroVM Support); rebuild it with cmd/oci-builder and re-run python3 scripts/ci/verify-oci-layout.py <dir> standalone for the precise reason
image architecture is 'X' but the host is 'Y'	build the image for the host's own architecture (-arch amd64 on an x86_64 host, -arch arm64 on an aarch64 host) - KVM cannot accelerate a cross-architecture guest, and this tooling deliberately doesn't fall back to slow emulation
Guest never becomes reachable / times out	run-microvm.sh prints the full guest console log on failure - look for a kernel panic or a missing boot-critical driver, and compare against scripts/microvm/kernel-common.config/kernel-<arch>.config
Kernel build fails	confirm the build toolchain is installed (see MicroVM Support step 2); build-kernel.sh requires a Linux host matching the target architecture and refuses to run on macOS or a mismatched host architecture
-sandbox on fails to start QEMU	your QEMU build lacks seccomp support; disable with MICROVM_QEMU_SANDBOX= scripts/microvm/run-microvm.sh ... (see MicroVM Support)
Checksum mismatch downloading the kernel source	this should never happen against an unmodified build-kernel.sh - if it does, treat it as a potential integrity issue (a compromised mirror, a MITM) and stop; don't bypass the check

Workflow / CI configuration

Symptom	Fix
python3 scripts/ci/verify-workflows.py fails locally	read the specific WORKFLOW_VALIDATION_FAILURE line(s) it prints - each names the exact file, job, and rule violated (unpinned action, missing timeout, wrong runner, missing set -euo pipefail, etc.); see Testing and CI/CD for the full rule set
verify-workflows.py errors with a Ruby-related failure	it shells out to ruby -ryaml -rjson to parse YAML without a Python YAML dependency - make sure ruby is on PATH
Coverage gate fails in ci-quality.yml	run go test ./... -coverprofile=coverage.out && go tool cover -func=coverage.out locally and add tests for whatever package dropped below 85% total

Scope reminders

This is a single-layer image generator, not a Dockerfile interpreter, registry client, image signer, SBOM generator, or runtime security policy engine. It does not prove an executable is actually static - you build it that way; CI's verify-elf.sh independently checks the result, but the Go builder itself trusts the caller's CGO_ENABLED=0 build. See Project scope, honestly stated.