Fixing Drone Builds Stuck Pending: Target the Right Runner

We recently hit a simple but frustrating Drone CI problem: a deployment build would just sit in pending.

Nothing was building. Nothing was failing. The job was just waiting for a free agent.

The catch was that there was no suitable agent available for that pipeline.

The Symptom

In Drone, a build can stay pending when it cannot be assigned to a runner. This can look like a capacity problem, but it is often a runner matching problem.

For this deployment, the production runner was an ARM64 Linux runner. The pipeline did not explicitly say that, so Drone could queue the build without a matching runner being selected.

The result was a silent-looking failure:

pending
waiting for a free agent

No useful application logs. No failed Docker command. No build output. Just a pipeline that never started.

The Fix

We updated .drone.yml to target the same runner method already working in the WeHireIt deployment:

kind: pipeline
type: docker
name: deploy-anecdotes-prod
platform:
  os: linux
  arch: arm64

That platform block is the important part.

It tells Drone that this job must run on a Linux ARM64 runner. Once the pipeline and runner agree on architecture, Drone can schedule the job correctly instead of leaving it stuck in the queue.

Why This Matters

When Drone says it is waiting for a free agent, the problem is not always that the runner is busy. It may be that no runner matches the pipeline.

Common causes include:

• The pipeline needs linux/arm64, but the config does not declare it.
• The runner is registered with labels or platform settings that the pipeline does not match.
• The available runner type does not match the pipeline type, such as Docker pipeline versus exec runner.
• The runner is offline, unhealthy, or unable to reach the Drone server.

In our case, the useful fix was not to restart the app or change Docker Compose. The deployment never got that far. The fix was to make the Drone pipeline schedulable.

The Practical Check

When a Drone build is stuck pending, check runner eligibility before debugging the application:

docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Image}}"
docker logs --since 30m drone-ci-drone-runner-1

Then compare the runner platform with the pipeline:

platform:
  os: linux
  arch: arm64

If the runner is ARM64, put that in the pipeline. If the pipeline requires Docker, make sure the runner is a Docker runner. If the runner uses labels, make sure the pipeline is asking for labels that actually exist.

The Lesson

A pending Drone build is a scheduling problem until proven otherwise.

Before digging through application logs, Docker Compose files, or nginx configs, first confirm that Drone has an eligible runner for the job. In this case, adding the ARM64 platform target changed the build from permanently pending to deployable.

That is the whole fix: make the pipeline match the runner that actually exists.