TeamCity "No idle compatible agents" build stuck in queue in CI

Unlike an incompatibility, this message means at least one agent can run the build but every compatible agent is currently occupied. The build waits until an agent frees up or capacity is added.

What this error means

The queued build shows "There are no idle compatible agents which can run this build" (or "Starts in ..." estimates). Compatible agents are listed but all are running other builds.

TeamCity

There are no idle compatible agents which can run this build.
Compatible agents: Agent-1 (busy), Agent-2 (busy)

Common causes

All compatible agents are busy

Demand exceeds the number of agents that satisfy the requirements, so builds queue behind running ones.

The pool has too few authorized agents

Only one or two agents are authorized for the pool, creating a bottleneck during peak build times.

How to fix it

Add or authorize more agents in the pool

Go to Administration, Agents, and authorize idle unauthorized agents into the pool.
For cloud agent profiles, raise the maximum number of running instances.
Re-check the queue: the estimated start time should drop as capacity increases.

Reduce contention with build priorities or fewer requirements

Set a build configuration priority so critical builds jump the queue, and remove over-narrow requirements that shrink the compatible-agent set.

How to prevent it

Size the agent pool for peak concurrency, not average load.
Use cloud agent profiles that scale instances up on demand.
Keep requirements broad enough that more than one agent qualifies.