highFoundationUSE#queue#executor#label#stuck

Jenkins build stuck in queue - no available executor

Build stuck in queue with 'Waiting for next available executor'

Likely source:availabilityscaling

Focused incident mode — strips away everything but this runbook.

Symptoms

  • Build stuck in queue with 'Waiting for next available executor'
  • Jenkins UI shows 'has the label <label> but the capacity is 0'
  • Multiple builds pile up in the queue with no progress

Jenkins' default label is 'master'. If a job specifies node: '<custom>' and no agent has that label, the job will queue forever.

Evidence to grab

Collect these artifacts before you change anything — they prove (or rule out) each cause.

  • Queue status

    curl -s -u <USER>:<TOKEN> '<JENKINS_URL>/queue/api/json?tree=items[task,why,inDate]'

  • Executor status

    curl -s -u <USER>:<TOKEN> '<JENKINS_URL>/api/json?tree=computer[name,executors[progress,displayName],oneOffline,description]'

Diagnostic flow

Run the steps in order, marking each claim confirmed or refuted. The evidence you gather feeds the ranked causes below.

Guided decision tree is ready.

Steps with commands, expected output, and pass/fail branches.

Ranked root causes

Evidence checklist

  • Queue shows 'has the label X but the capacity is 0'
  • All agents matching the label are offline or have all executors busy

Confirm before fixing

curl -s -u <USER>:<TOKEN> '<JENKINS_URL>/api/json?tree=computer[name,online,oneOffline]'
READ

List agent online status

Fix

curl -s -u <USER>:<TOKEN> -X POST '<JENKINS_URL>/computer/<AGENT_NAME>/launch'
CHANGE

Reconnect the offline agent

Resolution runbook

Apply from top to bottom after the cause is confirmed. Review every command before running it — risk tags are shown on each.

1
curl -s -u <USER>:<TOKEN> '<JENKINS_URL>/queue/api/json?tree=items[task{name},why]'
READ

Read the queue blockage reason

2
curl -s -u <USER>:<TOKEN> '<JENKINS_URL>/api/json?tree=computer[name,online,oneOffline,description]'
READ

Check agent status

3
curl -s -u <USER>:<TOKEN> '<JENKINS_URL>/computer/<AGENT_NAME>/api/json?tree=numExecutors,assignedLabels[name]'
READ

Verify executor count and labels

Prevention

  • Alert when Jenkins queue depth exceeds a threshold.
  • Use cloud agents (Kubernetes plugin, EC2 plugin) for elastic scaling.
  • Audit label usage across all jobs quarterly to remove orphaned labels.
  • Set agent numExecutors to at least 2 for parallel build support.

Related runbooks

Same stack, same failure family — worth a skim.

Jenkins agent node offline - remoting handshake failurecritical

Jenkins agent shows 'Offline' in the node management page

JenkinsIntermediateUSE2 causes
Open runbook
Jenkins workspace locked - concurrent build conflicthigh

Build fails with 'Workspace is locked by another build'

JenkinsFoundation2 causes
Open runbook

Commands marked READ CHANGE DESTRUCTIVE — never run DESTRUCTIVE commands against production data you cannot restore. Copy → verify → execute.