apache/pulsar · error · IllegalStateException

Not the leader

Error message

Not the leader

What it means

FunctionMetaDataManager.updateFunctionOnLeader only accepts function metadata updates when this worker currently holds the exclusive leadership producer (exclusiveLeaderProducer != null). When the worker is not the leader (or has just lost leadership), it throws IllegalStateException("Not the leader") so the caller can redirect the request to the current leader.

Source

Thrown at pulsar-functions/worker/src/main/java/org/apache/pulsar/functions/worker/FunctionMetaDataManager.java:210

     * @return true if function exists and false if it does not
     */
    public synchronized boolean containsFunction(String tenant, String namespace, String functionName) {
        return containsFunctionMetaData(tenant, namespace, functionName);
    }

    /**
     * Called by the worker when we are in the leader mode.  In this state, we update our in-memory
     * data structures and then write to the metadata topic.
     * @param functionMetaData The function metadata in question
     * @param delete Is this a delete operation
     * @throws IllegalStateException if we are not the leader
     * @throws IllegalArgumentException if the request is out of date.
     */
    public synchronized void updateFunctionOnLeader(FunctionMetaData functionMetaData, boolean delete)
            throws IllegalStateException, IllegalArgumentException {
        boolean needsScheduling;
        if (exclusiveLeaderProducer == null) {
            throw new IllegalStateException("Not the leader");
        }
        // Check first to avoid local cache update failure
        checkRequestOutDated(functionMetaData, delete);

        byte[] toWrite;
        if (workerConfig.getUseCompactedMetadataTopic()) {
            if (delete) {
                toWrite = "".getBytes();
            } else {
                toWrite = functionMetaData.toByteArray();
            }
        } else {
            ServiceRequest serviceRequest = new ServiceRequest();
            serviceRequest.setServiceRequestType(delete ? ServiceRequest.ServiceRequestType.DELETE
                            : ServiceRequest.ServiceRequestType.UPDATE);
            serviceRequest.setFunctionMetaData().copyFrom(functionMetaData);
            serviceRequest.setWorkerId(workerConfig.getWorkerId());
            serviceRequest.setRequestId(UUID.randomUUID().toString());

View on GitHub (pinned to 820761864e)

Solutions

1. Retry the operation against the current leader worker (query worker clustering / leader broker via the functions worker admin API or let the HTTP redirect layer forward it).
2. Catch IllegalStateException and re-discover the leader before retrying rather than hammering the stale worker.
3. Check worker logs for recent leadership changes; ensure worker config (e.g. use state storage / HA settings) isn't causing frequent leader flapping.
4. Ensure only one worker is configured as eligible leader if you run a single-worker setup so leadership is stable.

Example fix

// before
workerManager.updateFunctionOnWorkerLeader(tenant, namespace, functionName, functionMetaData, false);
// after
try {
    workerManager.updateFunctionOnWorkerLeader(tenant, namespace, functionName, functionMetaData, false);
} catch (IllegalStateException e) {
    if ("Not the leader".equals(e.getMessage())) {
        URI leader = functions.getLeader();
        // re-issue the request against the leader endpoint
    } else {
        throw e;
    }
}

URI leader = admin.functions().getLeader();
if (!leader.equals(currentWorkerUri)) {
    throw new IllegalStateException("Not the leader; redirect request to " + leader);
}

try {
    manager.updateFunctionOnLeader(meta, delete);
} catch (IllegalStateException e) {
    if ("Not the leader".equals(e.getMessage())) {
        rediscoverLeaderAndRetry(meta, delete);
    } else {
        throw e;
    }
}

When it happens

Trigger: Calling updateFunctionOnLeader (directly or via updateFunctionOnWorkerLeader / deregisterFunction) on a worker instance whose exclusiveLeaderProducer is null — i.e. the worker is not the functions worker leader, or leadership was just lost (failover) before this call.

Common situations: Client sent a register/update/delete function admin request to a non-leader worker; a leadership election happened concurrently and the old leader received a request after losing the exclusive producer; misconfigured worker with overlapping leaders during network partition.

Related errors

• State key needs to be specified
• The function registration references a different set of jar
• The function registration references a different set of clas
• No dependencies are registered for function ${fid}
• Leader not yet ready. Please retry again

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