apache/pulsar · error · RestException

Too few workers (need at least 2)

Error message

Too few workers (need at least 2)

What it means

This HTTP 400 error comes from the rebalance endpoint when the cluster has fewer than two workers. Rebalancing redistributes function instances between workers; with only one worker there is nothing to redistribute, so SchedulerManager throws TooFewWorkersException which WorkerImpl maps to this message.

Source

Thrown at pulsar-functions/worker/src/main/java/org/apache/pulsar/functions/worker/rest/api/WorkerImpl.java:232

        }
        throwIfNotSuperUser(authParams, "get list of connectors");
        return this.worker().getConnectorsManager().getConnectorDefinitions();
    }

    @Override
    public void rebalance(final URI uri, final AuthenticationParameters authParams) {
        if (!isWorkerServiceAvailable()) {
            throwUnavailableException();
        }
        throwIfNotSuperUser(authParams, "rebalance cluster");

        if (worker().getLeaderService().isLeader()) {
            try {
                worker().getSchedulerManager().rebalanceIfNotInprogress();
            } catch (SchedulerManager.RebalanceInProgressException e) {
                throw new RestException(Status.BAD_REQUEST, "Rebalance already in progress");
            } catch (SchedulerManager.TooFewWorkersException e) {
                throw new RestException(Status.BAD_REQUEST, "Too few workers (need at least 2)");
            }
        } else {
            WorkerInfo workerInfo = worker().getMembershipManager().getLeader();
            if (workerInfo == null) {
                throw new RestException(Status.INTERNAL_SERVER_ERROR, "Leader cannot be determined");
            }
            URI redirect =
                    UriBuilder.fromUri(uri).host(workerInfo.getWorkerHostname()).port(workerInfo.getPort()).build();
            throw new WebApplicationException(Response.temporaryRedirect(redirect).build());
        }
    }

    @Override
    public void drain(final URI uri, final String inWorkerId, final AuthenticationParameters authParams,
                      boolean calledOnLeaderUri) {
        if (!isWorkerServiceAvailable()) {
            throwUnavailableException();
        }

View on GitHub (pinned to 820761864e)

Solutions

1. Add at least one more worker to the cluster before rebalancing
2. Verify worker membership via GET /admin/v2/worker/cluster to see registered workers
3. Investigate why other workers left (crash, network partition, deregistration) if the cluster is supposed to be larger

List<WorkerInfo> workers = admin.functions().getCluster();
if (workers.size() < 2) throw new IllegalStateException("Need at least 2 workers before rebalance");

When it happens

Trigger: Calling POST /admin/v2/worker/rebalance when the membership manager sees only 1 worker in the cluster.

Common situations: Single-node dev/test clusters, clusters where other workers have crashed or been deregistered, or firing rebalance right after starting the first worker before others join.

Related errors

• Rebalance already in progress
• cluster data is required
• Cluster already exists
• Peer cluster ${peerCluster} does not exist
• Cluster not empty

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