apache/pulsar · error · SchedulerManager.TooFewWorkersException

Too few workers (need at least 2)

Error message

Too few workers (need at least 2)

What it means

SchedulerManager.rebalanceIfNotInprogress() refuses to trigger a cluster rebalance when the number of currently available workers is <= 1, throwing TooFewWorkersException ('Too few workers (need at least 2)'). Rebalancing assignments requires at least two live workers to move anything.

Source

Thrown at pulsar-functions/worker/src/main/java/org/apache/pulsar/functions/worker/SchedulerManager.java:249

            invokeScheduler();
            workerStatsManager.scheduleTotalExecTimeEnd();
        }, "Encountered error when invoking scheduler");
    }

    private Future<?> rebalance() {
        return scheduleInternal(() -> {
            workerStatsManager.rebalanceTotalExecTimeStart();
            invokeRebalance();
            workerStatsManager.rebalanceTotalExecTimeEnd();
        }, "Encountered error when invoking rebalance");
    }

    public Future<?> rebalanceIfNotInprogress() {
        if (rebalanceInProgress.compareAndSet(false, true)) {
            int numWorkers = getCurrentAvailableNumWorkers();
            if (numWorkers <= 1) {
                rebalanceInProgress.set(false);
                throw new TooFewWorkersException();
            }
            return rebalance();
        } else {
            throw new RebalanceInProgressException();
        }
    }

    private Future<?> drain(String workerId) {
        return scheduleInternal(() -> {
            workerStatsManager.drainTotalExecTimeStart();
            assignmentsMovedInLastDrain = invokeDrain(workerId);
            workerStatsManager.drainTotalExecTimeEnd();
        }, "Encountered error when invoking drain");
    }

    public Future<?> drainIfNotInProgress(String workerId) {
        if (drainInProgressFlag.compareAndSet(false, true)) {
            try {

View on GitHub (pinned to 820761864e)

Solutions

1. Start at least one more Functions worker and wait for it to register (it must be listed among available workers).
2. Check why other workers are down/disconnected (network, zookeeper/metadata store, config) and restore them.
3. Skip the rebalance call — with a single worker no redistribution is possible.

Example fix

// before
worker.rebalanceIfNotInprogress(); // throws when cluster has 1 worker
// after
if (worker.getCurrentAvailableNumWorkers() > 1) {
    worker.rebalanceIfNotInprogress();
} else {
    log.info("Skipping rebalance: fewer than 2 workers available");
}

// check available worker count first
if (numAvailableWorkers <= 1) {
    log.warn("Rebalance skipped: need at least 2 available workers");
    return;
}

try {
    worker.rebalanceIfNotInprogress();
} catch (TooFewWorkersException e) {
    log.warn("Cannot rebalance with <=1 worker; start more workers");
}

When it happens

Trigger: Calling the rebalance trigger (e.g. POST /rebalance on the worker REST API or CLI `pulsar-admin functions workers rebalance`) while only one (or zero) workers are registered/available.

Common situations: Single-node dev/test cluster where rebalance is meaningless; other workers crashed or are disconnected so only one worker is available; workers still initializing after a cluster restart.

Related errors

• Rebalance already in progress
• You must specify either a Fully Qualified Function Name (FQF
• You must specify a name for the function or a Fully Qualifie
• Cannot specify both jar and function-type
• No Function name specified

AI-assisted analysis of apache/pulsar@820761864e (2026-09-06). Data as JSON: /api/errors/c110ec3c5c647a3b. Report an issue: GitHub.