🚨 Jenkins Error: 'Waiting for next available executor' — Cause, Fix, and Troubleshooting Guide

Overview

A build is triggered but never starts. In the build queue and in the console log it sits, indefinitely, showing:

Waiting for next available executor
(pending—Waiting for next available executor on 'linux')

This is not an error in the traditional sense — Jenkins is telling you the job is runnable but there is no free executor that satisfies its constraints. Either every matching executor is busy, no node matches the job’s label, the matching agents are offline, or the number of executors available for this work is effectively zero. The job stays queued until a suitable executor frees up or you fix the mismatch.

Symptoms

• A build shows “pending” in the queue with the message Waiting for next available executor and never progresses to running.
• Hovering the queued item (or the build console) names a specific label, e.g. Waiting ... on 'linux'.
• Other jobs run fine while jobs targeting one label/agent all stall.
• The queue length grows during peak hours and drains slowly or not at all.
• Manage Jenkins > Nodes shows matching agents as offline, or all their executors marked busy.
• After setting the built-in node to 0 executors, jobs pinned to the controller never start.

Common Root Causes

• All matching executors are busy — every agent that satisfies the job’s label is already running builds; the job waits its turn (genuine capacity shortage).
• Label / agent mismatch — the job requests a label (agent { label 'gpu' } or a freestyle “Restrict where this project can be run”) that no online node provides, so nothing can ever pick it up.
• Matching agents are offline — the agents that carry the label are disconnected (crashed launcher, network, temporarily marked offline) so their executors don’t count.
• Controller executors set to 0 — a job pinned to the built-in node, or with no agent, has nowhere to run because the controller’s executor count was set to 0 (a common hardening step).
• Throttling / concurrency limits — Throttle Concurrent Builds, a lock/milestone, a quota, or “Do not allow concurrent builds” caps how many run at once, holding the rest in queue.
• Heavyweight vs flyweight executor confusion — a Declarative Pipeline’s top-level flyweight runs on the controller, but stage bodies need a heavyweight executor on an agent; if none matches the stage agent, the stage waits.
• Cloud agents not provisioning — an autoscaling cloud/Kubernetes template failed to launch new agents (quota, template error, credential issue), so demand never gets capacity.

How to diagnose

Read the queue’s own explanation first. Manage Jenkins (dashboard) shows the Build Queue; hover the stuck item or open Build Executor Status — Jenkins states exactly why it’s blocked (waiting for an executor, or “there are no nodes with the label”).

Confirm which label the job wants and which nodes provide it. In Manage Jenkins > Nodes, check each agent’s status and labels. To see the full picture programmatically, use the Script Console (read-only):

// Nodes, their labels, online state, and executor counts
Jenkins.instance.computers.each { c ->
  println "${c.displayName} online=${c.isOnline()} executors=${c.numExecutors} busy=${c.countBusy()}"
}
println "Built-in node executors: ${Jenkins.instance.numExecutors}"

// What is stuck in the queue and why
Jenkins.instance.queue.items.each { i ->
  println "${i.task.name} -> ${i.why}"
}

Check whether the requested label matches any node at all:

// Prints the nodes that satisfy label 'linux' — empty means a mismatch
println Jenkins.instance.getLabel('linux')?.getNodes()

If cloud agents should be scaling, review the cloud plugin’s provisioning log (Manage Jenkins > System Log, or the Kubernetes/EC2 cloud’s log) for failed launches.

Fixes

Fix 1: Add capacity or free busy executors

If diagnosis shows every matching agent is simply busy, the fix is more executors. Add agents with the label, or raise a node’s executor count in Manage Jenkins > Nodes > (agent) > Configure > Number of executors to match its CPU/RAM. Don’t over-subscribe — set executors to roughly the number of concurrent builds the host can handle.

Fix 2: Fix the label so a node matches

Make the job’s label match an online node, or add the label to a node. In a Declarative Pipeline, target a label that actually exists:

pipeline {
  agent { label 'linux' }   // must match a label on an ONLINE node
  stages {
    stage('Build') { steps { sh 'make' } }
  }
}

For freestyle jobs, check Configure > Restrict where this project can be run and correct the label expression. Add missing labels under Nodes > (agent) > Configure > Labels.

Fix 3: Bring matching agents back online

If the label’s agents are offline, reconnect them: relaunch the agent (JNLP/SSH), clear a manual “mark offline”, and fix the underlying launcher/network issue. See the sibling guide on agents dropping mid-build for launcher failures.

Fix 4: Give controller-pinned jobs somewhere to run

If a job with no agent (or agent none with controller steps) waits because the built-in node has 0 executors, either assign it an agent label or, if you intentionally keep the controller at 0 executors, move the work to an agent:

// Don't run heavyweight work on the controller; pin it to an agent
pipeline {
  agent none
  stages {
    stage('Build') {
      agent { label 'linux' }   // heavyweight executor on an agent
      steps { sh './build.sh' }
    }
  }
}

Keeping the built-in node at 0 executors is best practice — the fix is to route work to agents, not to add controller executors.

Fix 5: Relax throttling / concurrency limits

If a throttle, quota, or lock is holding builds, review the Throttle Concurrent Builds category limits, lock resource counts, or “Do not allow concurrent builds” and raise or scope them to what your capacity supports.

Fix 6: Fix cloud provisioning

If autoscaled agents aren’t appearing, resolve the cloud template error (cloud provider quota, bad image/credential, Kubernetes pod template) so new executors provision on demand.

What to watch out for

• “Waiting for next available executor” is a scheduling state, not a crash — read the queue’s why before changing anything.
• A label typo is the most common cause; a job requesting linux-x64 when nodes are labeled linux waits forever with no error.
• Keep the built-in (controller) node at 0 executors for security, but then ensure every job targets an agent, or those jobs will stall.
• Watch for one long-running or hung build hogging the only matching executor — set sensible timeouts so it can’t block the queue indefinitely.
• Right-size executor counts to host resources; over-subscribing turns a queue delay into OOMs and flaky builds.
• If demand is spiky, prefer autoscaling cloud agents over permanently marking the controller runnable.

Related

• Jenkins: queue item stuck — the closely related case where a queued item is blocked for a specific, reported reason.
• Jenkins: agent went offline during build — why the agents carrying your label may be unavailable.
• Jenkins Error: Jenkins is going to shut down — quiet mode also blocks new builds from starting, which can look like an executor shortage.