Buildkite job stuck "Waiting for agent" forever in CI

The job is queued and eligible but no agent is free to take it: either all matching agents are busy, or none are connected at all. Buildkite shows "Waiting for agent" until one frees up.

What this error means

A step sits on "Waiting for agent" with no error, sometimes for the whole build timeout, while other steps or builds run.

buildkite

Waiting for agent
(no agents available in queue "default" with free capacity)

Common causes

All matching agents are at capacity

Every connected agent for the queue is already running a job (each agent runs one job at a time), so the new job waits for a slot.

Autoscaling did not bring up agents

On an autoscaled pool, the scaler did not launch new agents fast enough (or hit a quota), so the queue has no free capacity.

How to fix it

Add agent capacity for the queue

Check how many agents serve the queue versus concurrent jobs requested.
Start more agents, or raise the autoscaler minimum/maximum for that queue.
Confirm the waiting job is picked up once capacity appears.

Terminal

# run several agents on one host
buildkite-agent start --spawn 4 --tags "queue=default"

Cap wait with a step timeout

Set timeout_in_minutes so a starved job fails visibly instead of hanging for the full build window.

pipeline.yml

steps:
  - command: "make test"
    timeout_in_minutes: 20
    agents:
      queue: "default"

How to prevent it

Provision enough agents (or autoscaling headroom) for peak concurrency per queue.
Alert when a queue depth grows faster than agent capacity.
Set timeout_in_minutes so starvation surfaces quickly.