Skip to content

Troubleshooting

Target audience: All users Goal: Diagnose and resolve common issues when working with StageX.

Quick Reference

Symptom See
Docker setup, permissions, disk space, bash version Dev Environment troubleshooting
Build failures, preseed, missing source tarballs Reproduce Builds troubleshooting
GPG signature problems, expired or missing keys Verify Attestations troubleshooting
OCI runtime errors, entrypoint, short names, auth OCI Integration troubleshooting
New package build failures, WORKDIR, missing deps Add Package troubleshooting
Upgrade failures, Python version bumps, build system changes Upgrade Package troubleshooting

Runtime & Build Failures

Stale Build Cache

Buildkit caches aggressively. If a recipe change or new source file isn't reflected in output, bypass the cache:

make NOCACHE=1

Daemon Not Running

The container daemon must be running before any build or pull command. See Dev Environment troubleshooting.

Short Name Resolution

OCI runtimes reject unqualified image names. Always use the full registry path:

podman pull docker.io/stagex/pallet-rust

Never stagex/pallet-rust alone. See OCI Integration troubleshooting.

Platform Mismatch

StageX builds for linux/amd64 by default. On ARM hosts, either match the platform or accept emulation overhead:

podman run --platform linux/amd64 docker.io/stagex/pallet-rust

See OCI Integration troubleshooting.

QEMU binfmt Missing

Cross-architecture builds need QEMU user-mode emulation registered in the kernel. See Dev Environment troubleshooting.

Version Compatibility

StageX requires minimum tool versions. Run the built-in check:

make compat

This verifies docker >= 29.1.5, buildx >= 0.30.1, jq >= 1.6, gpg >= 2.2, bash >= 5, and that Docker Engine uses containerd for image storage. See Dev Environment for installation steps.

Container Engine Auto-Detection

The Makefile auto-detects the container engine via $(shell command -v docker). If only Podman is installed and no docker alias exists, builds fail with docker: command not found. Create a symlink, an alias, or set BUILDER explicitly in your environment.

GPG & Signatures

GPG-related issues — missing public keys, expired certificates, WARNING: This key is not certified — are covered in the verify attestations guide. See that page for the full symptom table.

Reproducibility

If your local build produces a different digest than the committed reference:

  • Build cache contamination — run make NOCACHE=1 to force a clean build from source.
  • Wrong PLATFORM — the Makefile defaults to linux/amd64. Verify with uname -m and set PLATFORM if cross-building.
  • Different container engine — Podman and Docker may produce different layer metadata. Use the same engine for comparison.

For the complete troubleshooting table, see Reproduce Builds.

Getting Help

Channel Details
Matrix #stagex:matrix.org
IRC #stagex on OFTC
Issues Codeberg issue tracker

See Also