apache/seatunnel · error · IllegalArgumentException

Invalid target address: NULL

Error message

Invalid target address: NULL

What it means

joinViaTargetMember is invoked during TCP-IP cluster join with the address of the member to join. If the target address is null, meaning no master candidate could be resolved, the joiner throws IllegalArgumentException 'Invalid target address: NULL' instead of proceeding with a null address. It is a defensive check inside the join procedure reachable via doJoin.

Source

Thrown at seatunnel-engine/seatunnel-engine-server/src/main/java/org/apache/seatunnel/engine/server/joiner/LiteNodeDropOutTcpIpJoiner.java:110

            long maxJoinMergeTargetMillis =
                    node.getProperties().getMillis(ClusterProperty.MAX_JOIN_MERGE_TARGET_SECONDS);
            joinViaTargetMember(targetAddress, maxJoinMergeTargetMillis);
            if (!clusterService.isJoined()) {
                joinViaPossibleMembers();
            }
        } else if (joinConfig.getTcpIpConfig().getRequiredMember() != null) {
            Address requiredMember = getRequiredMemberAddress();
            long maxJoinMillis = getMaxJoinMillis();
            joinViaTargetMember(requiredMember, maxJoinMillis);
        } else {
            joinViaPossibleMembers();
        }
    }

    private void joinViaTargetMember(Address targetAddress, long maxJoinMillis) {
        try {
            if (targetAddress == null) {
                throw new IllegalArgumentException("Invalid target address: NULL");
            }
            if (logger.isFineEnabled()) {
                logger.fine("Joining over target member " + targetAddress);
            }
            if (targetAddress.equals(node.getThisAddress()) || isLocalAddress(targetAddress)) {
                clusterJoinManager.setThisMemberAsMaster();
                return;
            }
            long joinStartTime = Clock.currentTimeMillis();
            Connection connection;
            while (shouldRetry() && (Clock.currentTimeMillis() - joinStartTime < maxJoinMillis)) {
                ServerConnectionManager connectionManager =
                        node.getServer().getConnectionManager(MEMBER);
                connection = connectionManager.getOrConnect(targetAddress);
                if (connection == null) {
                    connectionManager.blockOnConnect(targetAddress, JOIN_RETRY_WAIT_TIME, 0);
                    continue;
                }

View on GitHub (pinned to cf67b549a7)

Solutions

1. Ensure the target/master node is running and reachable before starting this node.
2. Verify the 'member-list' addresses and ports in the hazelcast TCP-IP join config are correct.
3. Check DNS resolution and firewall/network rules between nodes.
4. Retry the join after the master becomes available; review cluster logs for why the target address resolved to null.

// before starting the node
nc -z <masterHost> <clusterPort> && echo reachable || echo 'master not reachable'

try {
    startNode();
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("Invalid target address")) {
        // wait for master then retry join
        Thread.sleep(joinRetryMs);
        startNode();
    } else throw e;
}

When it happens

Trigger: A lite member configured with a TCP-IP join list where all configured member addresses are unreachable/unresolvable, so the resolved target member address is null when joinViaTargetMember runs; or the join target lookup returns null due to network/DNS failure.

Common situations: Master node down or not yet started when a lite (client-coordination) node tries to join; wrong host/port listed in the member-list config; DNS name not resolvable in the container environment; firewall blocking the cluster port.

Related errors

• Failed to get cluster members information
• ${ClusterProperty.TCP_JOIN_PORT_TRY_COUNT} must be greater t
• Failed to get HTTP port from member {}, skip.
• Failed to fetch metadata from Gravitino for metadata: %s
• fail get tableSchema:

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