🚨 Jenkins Error: '(pending—Waiting for next available executor)' — Queue Item Stuck: Cause, Fix, and Troubleshooting Guide

Overview

A build is triggered but never starts. It sits in the queue indefinitely, and hovering the queued item in the UI shows a reason string explaining why Jenkins can’t schedule it:

(pending—Waiting for next available executor)

or, when the requested label matches no node at all:

(pending—There are no nodes with the label 'linux-arm64')
Jenkins doesn't have label linux-arm64

The queue item is not an error in the “stack trace” sense — Jenkins is telling you it cannot place the build on any executor that satisfies the job’s requirements. The reason string is the single most important clue: it names exactly what’s blocking scheduling. Fix what the reason says, and the item schedules immediately.

Symptoms

• A build shows in the left-hand Build Queue with a clock/pending icon and never transitions to running.
• Hovering the item shows a reason like Waiting for next available executor or There are no nodes with the label 'X'.
• Other jobs on other labels run fine — only jobs needing a specific label/node hang.
• The queue grows over time as more triggers land on the same unsatisfiable requirement.
• Cloud agents (EC2/Kubernetes) that should auto-provision never appear.
• After putting Jenkins in “Prepare for Shutdown” (quiet mode), nothing new starts.

Common Root Causes

• Label matches no online node — the job requests agent { label 'X' } but no online node advertises label X (typo, node removed, or label never assigned). Reason: Jenkins doesn't have label X / no nodes with the label.
• All matching nodes are offline — the label exists but every node carrying it is offline (disk threshold, disconnected agent, manually marked offline).
• No free executors — matching nodes are online but every executor is busy; the item legitimately waits (Waiting for next available executor). If it never clears, executor count is too low or a build is wedged.
• Executor count set to 0 — a node (often the built-in/controller) has # of executors set to 0, so it can run nothing.
• Cloud provisioning failing — the cloud plugin should spin up an agent for the label but can’t (bad credentials, quota/limit, subnet/AMI/image error), so the label never comes online.
• Quiet / shutdown mode — Jenkins is in “Prepare for Shutdown”; it drains running builds and refuses to start new ones. Reason mentions Jenkins is going to shut down.
• Upstream/throttle dependency — a throttle, lock (Lockable Resources), or upstream trigger is holding the item until a resource frees.

How to diagnose

Read the queue item’s reason first — it tells you which case you’re in. In the UI, hover the queued build, or use the Script Console for the exact machine-readable reasons:

// Manage Jenkins → Script Console — list every queued item and WHY it's blocked
Jenkins.instance.queue.items.each { item ->
  println "${item.task.name} :: ${item.getWhy()}"
}

List nodes, their online state, labels, and free executors so you can see whether the label is actually available:

Jenkins.instance.computers.each { c ->
  println "${c.displayName} online=${c.isOnline()} " +
          "idleExecutors=${c.countIdle()}/${c.numExecutors} " +
          "labels=${c.node?.labelString}"
}

Confirm whether the requested label resolves to any node at all:

def label = Jenkins.instance.getLabel('linux-arm64')
println "nodes for label: ${label?.nodes}"   // empty => Jenkins doesn't have label

Check for quiet/shutdown mode and cloud provisioning problems:

Manage Jenkins → top banner shows "Jenkins is going to shut down" if in quiet mode
Manage Jenkins → Nodes → <cloud> → provisioning errors
Manage Jenkins → System Log → cloud plugin (EC2/Kubernetes) provisioning failures

Fixes

1. Fix the label so it matches an online node

Make sure the label the job asks for is actually assigned to a running node. Assign the label in Manage Jenkins → Nodes → agent-01 → Configure → Labels, or correct the job to request a label that exists:

pipeline {
  agent { label 'linux && docker' }   // must match labels advertised by an ONLINE node
  stages {
    stage('build') { steps { sh 'make' } }
  }
}

If you meant “any agent”, use agent any. Watch for typos and case — labels are case-sensitive.

2. Bring matching nodes back online

If the label exists but its nodes are offline, fix the underlying reason (often disk threshold or a disconnected agent) and reconnect. In Manage Jenkins → Nodes → agent-01, click “Bring this node back online” once healthy, or relaunch the agent. A disk-threshold offline needs space reclaimed first — see the related guide.

3. Give the label enough executors

If the item shows Waiting for next available executor and never clears, add executors or nodes for that label. Set # of executors on the node (never leave a build node at 0). For the controller’s built-in node, keep executors low or 0 by design and run work on agents instead. Add capacity for busy labels by adding nodes or raising executor counts.

4. Fix cloud provisioning

If a cloud should supply the label, resolve the provisioning error the log names (credentials, region/quota, AMI/pod template). For Kubernetes agents, ensure the pod template’s label matches the job:

podTemplate(label: 'linux-arm64', containers: [
  containerTemplate(name: 'build', image: 'alpine:3.20', command: 'cat', ttyEnabled: true)
]) {
  node('linux-arm64') {
    stage('build') { container('build') { sh 'uname -m' } }
  }
}

Confirm the cloud’s instance cap isn’t already reached and credentials/quotas allow new agents.

5. Leave quiet/shutdown mode

If Jenkins is in “Prepare for Shutdown”, nothing new starts by design. Cancel it in the top banner (“Cancel Shutdown”) or via CLI once you’re ready to accept builds:

java -jar jenkins-cli.jar -s https://jenkins.example.com/ cancel-quiet-down

6. Clear a wedged item or resource

To unblock a queue held by a stale lock/throttle, release the resource, or cancel the stuck item:

Jenkins.instance.queue.items.findAll { it.task.name == 'my-job' }.each {
  Jenkins.instance.queue.cancel(it)
}

What to watch out for

• The queue reason string is authoritative — read it before changing anything. “No node with label X” and “waiting for executor” have completely different fixes.
• Labels are case-sensitive and typo-prone. A renamed or decommissioned node silently strips its labels, stranding every job that needs them.
• Never run all work on the controller’s built-in executors; keep them at 0–2 and use agents, or a single wedged build blocks everything.
• Cloud provisioning failures are quiet — the label simply never appears. Watch the cloud plugin’s log and set alerts on long queue times.
• A build stuck Waiting for next available executor can also mean a node went offline for disk or an agent dropped — check node health, not just the job. The free incident assistant can help correlate a stuck queue with node and provisioning events.

Related

• Jenkins Error: Waiting for next available executor — the executor-starvation case in depth, when nodes are online but every executor is busy.
• Jenkins Error: Disk space is below threshold — a node taken offline for disk strands every job that needs its label.
• Jenkins Error: Agent went offline during the build — offline agents remove their labels from the pool, stalling the queue.