jenkinsci/jenkins · error · IllegalStateException

Build scheduling Refused by an extension, hence not in Queue

Error message

Build scheduling Refused by an extension, hence not in Queue.

What it means

Thrown by `BuildCommand.run()` at line 172 (constant `BUILD_SCHEDULING_REFUSED`) when the user passed -w, -s, or -f (wait/sync/follow) but `ParameterizedJobMixIn.scheduleBuild2(...)` returned a null `Queue.Item`, i.e. no future `f` exists. A null return means an extension (a Queue blocking handler, QueueSorter, or a plugin like Priority Sorter / Job Restrictions / a custom QueueDecisionHandler) refused to place the build in the queue, so there is nothing to wait on.

Source

Thrown at core/src/main/java/hudson/cli/BuildCommand.java:172

                return 0;
        }

        if (!job.isBuildable()) {
            String msg = Messages.BuildCommand_CLICause_CannotBuildUnknownReasons(job.getFullDisplayName());
            if (job instanceof ParameterizedJobMixIn.ParameterizedJob && ((ParameterizedJobMixIn.ParameterizedJob) job).isDisabled()) {
                msg = Messages.BuildCommand_CLICause_CannotBuildDisabled(job.getFullDisplayName());
            } else if (job.isHoldOffBuildUntilSave()) {
                msg = Messages.BuildCommand_CLICause_CannotBuildConfigNotSaved(job.getFullDisplayName());
            }
            throw new IllegalStateException(msg);
        }

        Queue.Item item = ParameterizedJobMixIn.scheduleBuild2(job, 0, new CauseAction(new CLICause(Jenkins.getAuthentication2().getName())), a);
        QueueTaskFuture<? extends Run<?, ?>> f = item != null ? (QueueTaskFuture) item.getFuture() : null;

        if (wait || sync || follow) {
            if (f == null) {
                throw new IllegalStateException(BUILD_SCHEDULING_REFUSED);
            }
            Run<?, ?> b = f.waitForStart();    // wait for the start
            stdout.println("Started " + b.getFullDisplayName());
            stdout.flush();

            if (sync || follow) {
                try {
                    if (consoleOutput) {
                        // read output in a retry loop, by default try only once
                        // writeWholeLogTo may fail with FileNotFound
                        // exception on a slow/busy machine, if it takes
                        // longish to create the log file
                        int retryInterval = 100;
                        for (int i = 0; i <= retryCnt; ) {
                            try {
                                b.writeWholeLogTo(stdout);
                                break;
                            }

View on GitHub (pinned to 2e228ff40b)

Solutions

1. Cancel Jenkins quiet-down (UI: 'Cancel quiet down', or `java -jar jenkins-cli.jar cancel-quiet-down`) then retry the build with -s/-w/-f.
2. Drop the -w/-s/-f flag so the command just submits the build (the null-future check is only inside the wait block); then inspect the queue separately.
3. Audit installed plugins for queue-restricting extensions (Priority Sorter, Job Restrictions, throttle-concurrency) and check the queue/executor state before submitting.

Example fix

// before: build may be refused and -s has no future to wait on
//   java -jar jenkins-cli.jar build myjob -s
//
// after: ensure not in quiet-down, then submit; optionally drop the wait flag
//   java -jar jenkins-cli.jar cancel-quiet-down
//   java -jar jenkins-cli.jar build myjob -s
// (if still refused, submit without -s and poll the queue/HTTP API separately)

// scheduleBuild2 returning null only matters when you wait (-w/-s/-f);
// submit without waiting, or detect null and report gracefully.
try {
    // run build -s/-f
} catch (IllegalStateException e) {
    if (e.getMessage().equals(BuildCommand.BUILD_SCHEDULING_REFUSED)) {
        // extension refused queueing: check quiet-down and queue plugins
        System.err.println("Build refused by queue extension or quiet-down; "
          + "run 'cancel-quiet-down' and retry, or submit without -s");
    } else throw e;
}

When it happens

Trigger: Running `java -jar jenkins-cli.jar build <job> -s` (or -w/-f) where `scheduleBuild2` returns null because Jenkins is in quiet-down mode, a plugin vetoes queueing, the job has no available executors and a queue filter blocks it, or the item is collapsed by a QueueDecisionHandler.

Common situations: Jenkins in 'Prepare for Shutdown' / quiet-down (which blocks new items), a Queue plugin restricting concurrency, all executors offline with a 'block build when no node' filter, or plugin upgrades that changed queue acceptance behavior.

Related errors

• Cannot build {0} for unknown reasons.
• Cannot build {0} because its configuration has not been save
• No such build #
• Permalink produced no build
• {} is not parameterized but the -p option was specified.

AI-assisted analysis of jenkinsci/jenkins@2e228ff40b (2026-08-14). Data as JSON: /api/errors/730d0b97446d8844. Report an issue: GitHub.