agent-troubleshooting

Buildkite jobs may remain unassigned due to queue mismatches, missing agent tags, or agent connectivity issues. Diagnosing the build state and cluster configuration helps locate where the job is blocked and identifies the specific bottleneck preventing agent assignment.

To diagnose a stuck Buildkite job, provide the build number or URL. The system queries builds, clusters, and queues to inspect the job state, interprets whether it is scheduled or assigned, and walks you through specific diagnostic commands to resolve the bottleneck.

A Buildkite queue mismatch prevents jobs from matching available agents, causing scheduled jobs to block indefinitely. Inspecting the queue configuration and comparing it against the agent's target queue identifies the mismatch and restores agent throughput.

Yes, you can troubleshoot agent connectivity issues across Buildkite clusters. The system queries cluster configurations and agent states to determine if agents are failing to accept jobs, providing actionable remediation steps to restore pipeline execution.

When a Buildkite job is accepted but not running, the agent may be experiencing connectivity loss or execution blocks. Interpreting the agent state helps differentiate between queue mismatches and active cluster bottlenecks to determine the correct fix.

The best way to fix a Buildkite agent bottleneck is to retrieve the build details, inspect the cluster and queue assignments, and apply the provided diagnostic commands. This reveals whether tag mismatches or connectivity failures are stopping job execution.