How do agent labels route a Jenkins build to the right machine, and what happens to a build whose `agent { label 'gpu && linux' }` expression matches no online agent?

## Labels are capabilities, not hostnames A Jenkins agent has a name (`build-node-07`) and a label string configured on the node. Jenkins treats the node's own name as an implicit label too, so `node('build-node-07')` pins to that exact machine. Almost always you should not do that. Pinning to a hostname makes the pipeline break when the machine is replaced, and it prevents Jenkins from balancing work. Labels exist so a Jenkinsfile can say what it *needs* — `linux`, `docker`, `windows`, `jdk17`, `gpu`, `arm64` — and let the scheduler find something that has it. A node's label field is a space-separated list: ``` linux docker jdk17 build ``` That node satisfies `linux`, `docker`, `linux && docker`, `docker || windows`, and `linux && !windows`. ## The expression language Label expressions support boolean operators: `&&` (and), `||` (or), `!` (not), parentheses for grouping, and quoting for labels containing spaces or special characters. Jenkins also supports `->` (implies) and `<->` (if and only if), which are rarely worth the confusion they cause. In practice, three shapes cover nearly everything: ```groovy agent { label 'linux' } // one capability agent { label 'linux && docker' } // conjunction of capabilities agent { label 'linux && !deprecated' } // exclude a retiring pool ``` Declarative pipelines write it as `agent { label '…' }`; scripted pipelines write `node('…') { … }`, taking the same expression string. Freestyle jobs have a "Restrict where this project can be run" field that accepts the same syntax. ## What the scheduler does with it When a build needs an executor, Jenkins builds the set of nodes satisfying the expression, filters out nodes that are offline, have no free executor, or are restricted from running that job, and assigns the build. Where several nodes qualify, the selection depends on the configured load-balancing strategy — do not promise an interviewer that Jenkins picks the least-loaded machine by CPU; the default behaviour is not a resource-aware scheduler, and you should not design around a specific choice. ## The no-match behaviour is the interesting half This is where the question usually goes. If no node satisfies the expression, the build **queues**. It does not error, it does not time out by default, and it does not fall back to any other node. Open the build queue in the UI and hover the pending item and Jenkins will tell you why it is stuck — typically that there are no nodes with the requested label, or that all matching nodes are offline or busy. Common root causes: - A typo, or a case mismatch: labels are case-sensitive, so `Linux` and `linux` are different labels. - The agent that carried the label was removed, renamed, or its label list was edited. - Every matching agent is offline — a disconnected agent still exists in the configuration, so the label "exists" but nothing can run. - The job is restricted by a folder or authorization setting from using the nodes that do match. Two defences matter. First, wrap pipelines in a timeout so a stuck build eventually fails loudly instead of sitting in the queue for a weekend: ```groovy options { timeout(time: 1, unit: 'HOURS') } ``` Note the important subtlety — a top-level `timeout` option in a declarative pipeline starts counting once the pipeline begins, so it does cover queue time for stage-level agents but you should verify the behaviour you rely on. Second, monitor queue depth and the age of the oldest queue item; a queue that only grows is the signal that a label no longer resolves. ## Clouds change the picture A configured cloud — the Kubernetes plugin, the EC2 plugin, the Docker plugin — advertises labels of its own through its templates. When a build asks for a label that only a cloud template provides, Jenkins provisions a new agent (a pod, an instance, a container), it connects, runs the build, and is torn down. From the Jenkinsfile the syntax is identical; the difference is that the label resolves to capacity that does not exist yet. This is why the same `agent { label 'linux' }` can mean "one of our four VMs" in one installation and "a fresh pod per build" in another. ## Designing a label taxonomy Treat labels as an interface between pipelines and infrastructure. Name capabilities (`docker`, `jdk17`, `arm64`, `gpu`), not owners or hostnames, so you can replace machines behind the label. Keep the vocabulary small and documented — every extra label is a way for a pipeline to become unschedulable when the fleet changes. When you retire a pool, add the new label to the new nodes *before* removing the old one, so no pipeline is stranded mid-migration.