Buildkite "No agents matching the following tags" in CI

By Daniel Zoghalchali·Latchkey

A job requests agents with a specific queue or tag, and no currently connected agent advertises all of those tags. Buildkite holds the job as "waiting" until a matching agent appears.

What this error means

The build shows a step stuck in "waiting" with a banner "No agents matching the following tags" listing the required tags such as queue=deploy.

Waiting for agent
No agents matching the following tags:
  queue=deploy
  os=linux

Common causes

Step targets a queue no agent serves

The step (or pipeline default) sets agents: { queue: "deploy" } but every connected agent runs a different queue, so nothing matches.

A tag typo or a stopped agent pool

The required tag is misspelled, or the agents that carry it are offline, leaving no candidate for the job.

How to fix it

Align step tags with a live agent

1. Open Agents in the dashboard and read the tags of the connected agents.
2. Set the step agents block to a queue and tags that at least one online agent advertises.
3. Re-run the build so the job can be dispatched.

steps:
  - command: "make deploy"
    agents:
      queue: "default"
      os: "linux"

Start an agent that advertises the required tags

If the queue is correct, bring up an agent tagged for it so the waiting job has a target.

buildkite-agent start --tags "queue=deploy,os=linux"

How to prevent it

• Keep step queue/tag values in sync with the tags your agents advertise.
• Alert when a queue has zero connected agents.
• Use a small set of documented queue names to avoid typos.

Frequently asked questions

Related guides

References

• GitHub Actions documentation