apache/seatunnel · warning · RetryableHazelcastException

master not yet known

Error message

master not yet known

What it means

AbstractSeaTunnelMessageTask.getInvocationBuilder needs the cluster master address to route SeaTunnel operations (job submit, etc.). If nodeEngine.getMasterAddress() returns null - the member has not yet discovered who the master is - it throws RetryableHazelcastException 'master not yet known', signalling the caller to retry later. This is an expected transient condition during cluster formation.

Source

Thrown at seatunnel-engine/seatunnel-engine-server/src/main/java/org/apache/seatunnel/engine/server/protocol/task/AbstractSeaTunnelMessageTask.java:83

    @Override
    public Permission getRequiredPermission() {
        return null;
    }

    @Override
    public String getDistributedObjectName() {
        return null;
    }

    protected <V> Data toData(V v) {
        return nodeEngine.getSerializationService().toData(v);
    }

    @Override
    protected InvocationBuilder getInvocationBuilder(Operation operation) {
        Address masterAddress = nodeEngine.getMasterAddress();
        if (masterAddress == null) {
            throw new RetryableHazelcastException("master not yet known");
        }
        return nodeEngine
                .getOperationService()
                .createInvocationBuilder(SeaTunnelServer.SERVICE_NAME, operation, masterAddress);
    }

    protected SeaTunnelServer getSeaTunnelService() {
        return getService(SeaTunnelServer.SERVICE_NAME);
    }
}

View on GitHub (pinned to cf67b549a7)

Solutions

1. Retry the request after a short delay - the exception is explicitly RetryableHazelcastException.
2. Wait for the node to fully join the cluster (check 'master address' in logs) before submitting jobs.
3. Verify cluster connectivity and that the master node is up and elected.
4. If persistent, inspect Hazelcast join config and network partitions between members.

// wait until master is known before first request
await()
    .atMost(60, SECONDS)
    .pollInterval(2, SECONDS)
    .until(() -> clusterMemberHasMaster(nodeAddress));

catch (HazelcastException e) {
    if (e instanceof RetryableHazelcastException || e.getMessage().contains("master not yet known")) {
        Thread.sleep(backoffMs);
        return sendWithRetry(request, attempts - 1);
    }
    throw e;
}

When it happens

Trigger: Submitting a REST/protocol request (e.g. via the REST API v2 or client task) to a node that has not yet joined a formed cluster or has not received master information from Hazelcast; master node just started or split-brain healing in progress.

Common situations: Client sends a request immediately after the SeaTunnel node starts, before cluster join completes; all nodes started simultaneously and master election is still ongoing; network instability making the master temporarily unknown.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

Related errors

• cluster have no master node
• SeaTunnel server is not available on this node.
• Caller ${callerAddress} cannot get metrics because it is not
• Caller ${callerAddress} cannot get taskGroupLocation metrics
• Failed to get HTTP port from member {}, skip.

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/0f5207f430000b3a. Report an issue: GitHub.