Depot Runners Troubleshooting: Common Setup Issues
Adopting a drop-in managed runner like Depot is usually smooth, but a handful of predictable issues trip people up. Here are the common ones with general, verifiable causes and fixes.
Because Depot 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 Depot's documented setup work; for anything account-specific, check depot.dev/docs and Depot support.
Runner not picked up (job stays queued)
The most common cause is a runs-on label that does not match a Depot runner label, or the Depot GitHub App / organization connection not being in place. Fix: confirm the exact label from Depot's docs for the runner type and size you want, and confirm the Depot GitHub App is installed and connected to the GitHub org that owns the repository. Per Depot's docs, adoption is the runs-on change plus that org connection; if either is missing, GitHub has nothing to schedule the job onto and it waits.
Works in one repo but not another (project / org setup)
Depot runner usage is scoped to a Depot project and organization. If a workflow runs fine in one repository but a second repository's job is never picked up, the second repo is usually not covered by the connected org or project. Fix: make sure every repository you want on Depot runners is under the connected GitHub organization and mapped to the Depot project, then retry.
Cache not warming initially (first runs feel slow)
Depot's integrated distributed cache delivers its speedups once it is populated. On the very first runs there is little to hit, so early jobs can feel no faster than before. This is expected, not a bug. Fix: run the pipeline a few times so the cache warms; Depot documents the cache working with no config changes, so you should not need special keys. If it never warms across many runs, check that jobs are actually landing on Depot runners (see the runs-on label issue above).
Docker build vs runner product confusion
A frequent mix-up: Depot's marketing "up to 55x faster builds" figure refers to its remote Docker image build product, not its GitHub Actions runners. If you enabled Depot runners expecting a 55x runner speedup, that is the wrong expectation. Runners are marketed as up to 3x faster than GitHub-hosted (the Ultra Runners on Genoa CPUs). Fix: to get the Docker-build acceleration, use Depot's Docker build product; its BuildKit builders can run next to the runners. Keep the two products distinct when reading benchmarks.
Trial or plan minute limits
Depot runners are billed per minute (tracked per second, no enforced one-minute minimum per Depot). The Developer plan includes 2,000 minutes then $0.004/min, and the Startup plan includes 20,000 minutes. During the 7-day free trial, a large pipeline can burn through included minutes and jobs may stop or start billing. Fix: monitor usage in the Depot dashboard, size your evaluation to fit included minutes, and verify current allowances at depot.dev/pricing before rolling out widely.
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 Depot.