WarpBuild Runners Troubleshooting: Common Setup Issues
Adopting a drop-in managed runner like WarpBuild is usually smooth, but a handful of predictable issues trip people up. Here are the common ones with general, verifiable causes and fixes based on WarpBuild's own docs.
Because WarpBuild runners are a drop-in replacement adopted by changing the runs-on label, most problems are configuration and connection issues rather than deep failures. Below are the recurring ones and how to resolve them. These are general causes based on how drop-in managed runners and WarpBuild's documented setup work; for anything account-specific, check warpbuild.com/docs and WarpBuild support.
Runner not picked up (job stays queued)
The most common cause is the WarpBuild GitHub bot not being installed on the repository, or a runs-on label that does not match a WarpBuild runner. Fix: per WarpBuild's quick-start, install the WarpBuild GitHub bot and grant it access to the repos you want to run on WarpBuild, then confirm the exact runner label (for example warp-ubuntu-latest-x64-4x) from WarpBuild's cloud-runners docs. If either the bot or the correct label is missing, GitHub has nothing to schedule the job onto and it waits.
Cache warning: "zstd version: null"
According to WarpBuild's caching docs, the warning zstd version: null means the zstd compression tool is not available in the environment, so the cache action falls back to gzip. WarpBuild notes all WarpBuild runners have zstd available, so this typically happens when the cache action runs inside a container that lacks zstd. Fix: ensure the compression tools available in the current environment match those used when the cache was saved, for example by installing zstd in the container image, so cache save and restore stay consistent.
Docker layer cache step fails on small runners
WarpBuild's caching docs note this error usually occurs when the Docker layers are large and the runner size is small; for example layers exceeding several GB on a 2x runner can trigger failures. Fix: move the job to a larger runner size (for instance warp-ubuntu-latest-x64-8x or larger) so there is enough disk and memory headroom for the layers, then retry.
Cache restore not working (enable debug logging)
If a cache restore is not producing hits, WarpBuild's caching docs recommend rerunning your workflow with debug logging enabled and checking the restore step for warnings or errors. The docs also note that using cache action versions older than v1.4.5 may cause issues, so pin to a current version. Fix: turn on Actions debug logging, read the restore-step output, and upgrade WarpBuilds/cache to the latest v1 release before further debugging.
Docker build slower than expected or billed twice
A frequent surprise with WarpBuild's Remote Docker Builders is billing: per WarpBuild's docs, you are charged separately for the GitHub Actions runner and the WarpBuild Docker builder. Another documented cause of slowness is the eventually-consistent layer cache: a layer built in one job may not be immediately available to another concurrent build, but becomes available after synchronization. Fix: expect two line items when using remote builders, and do not assume concurrent builds share cache instantly; sequential or warmed builds see the best hit rate.
Docker multi-arch "exec format error"
When building for arm64 with WarpBuild's Remote Docker Builders, an exec format error usually means the builder profile does not have both architectures enabled. WarpBuild's docs note multi-arch builds run amd64 and arm64 on separate builder instances rather than via QEMU, so the target architecture must be enabled on the profile. Fix: verify your builder profile has both linux/amd64 and linux/arm64 enabled before running a multi-platform build. WarpBuild also recommends invoking docker-configure immediately before the build step to avoid idle timeouts.
Snapshot runner state missing after reboot
With WarpBuild snapshot runners, a common gotcha is losing files you expected to persist. Per WarpBuild's snapshot docs, the /tmp directory is cleaned on reboots and will not persist state across a snapshot boot. WarpBuild also recommends removing credentials before snapshotting (for example rm -rf $HOME/.ssh $HOME/.aws and git clean -ffdx) so secrets are not baked into the image. Fix: store anything you need to survive a snapshot boot outside /tmp, and clean credentials before saving the snapshot.
When the real problem is flaky failures
If your jobs are picked up and fast but still fail intermittently on out-of-memory kills, disk-full errors, or registry timeouts, no runner-speed tuning fixes that. Latchkey is a drop-in managed runner (also a runs-on swap) built around self-healing CI: it detects, diagnoses, fixes, and retries those transient and mechanical failures automatically, with up to 58% lower per-minute cost than GitHub Actions. If troubleshooting keeps landing on flaky re-runs, it is worth piloting alongside WarpBuild.