apache/seatunnel · critical · IllegalArgumentException

${ClusterProperty.TCP_JOIN_PORT_TRY_COUNT} must be greater t

Error message

${ClusterProperty.TCP_JOIN_PORT_TRY_COUNT} must be greater than zero! Current value: ${tryCount}

What it means

At node startup, LiteNodeDropOutTcpIpJoiner reads the Hazelcast/SeaTunnel cluster property TCP_JOIN_PORT_TRY_COUNT, which controls how many TCP ports the joiner will try when connecting to the master. If the configured value is zero or negative, the constructor throws IllegalArgumentException immediately because joining would be impossible or would loop unboundedly. This is a fail-fast configuration sanity check during cluster join initialization.

Source

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

import static com.hazelcast.internal.cluster.impl.ClusterServiceImpl.SERVICE_NAME;
import static com.hazelcast.internal.util.EmptyStatement.ignore;
import static com.hazelcast.internal.util.FutureUtil.RETHROW_EVERYTHING;
import static com.hazelcast.internal.util.FutureUtil.returnWithDeadline;

public class LiteNodeDropOutTcpIpJoiner extends TcpIpJoiner {

    private static final long JOIN_RETRY_WAIT_TIME = 1000L;
    private static final int MASTERSHIP_CLAIM_TIMEOUT = 10;

    private final int maxPortTryCount;
    private volatile boolean claimingMastership;
    private final JoinConfig joinConfig;

    public LiteNodeDropOutTcpIpJoiner(Node node) {
        super(node);
        int tryCount = node.getProperties().getInteger(ClusterProperty.TCP_JOIN_PORT_TRY_COUNT);
        if (tryCount <= 0) {
            throw new IllegalArgumentException(
                    String.format(
                            "%s must be greater than zero! Current value: %d",
                            ClusterProperty.TCP_JOIN_PORT_TRY_COUNT, tryCount));
        }
        maxPortTryCount = tryCount;
        joinConfig = getActiveMemberNetworkConfig(config).getJoin();
    }

    @Override
    public boolean isClaimingMastership() {
        return claimingMastership;
    }

    private int getConnTimeoutSeconds() {
        return joinConfig.getTcpIpConfig().getConnectionTimeoutSeconds();
    }

    @Override

View on GitHub (pinned to cf67b549a7)

Solutions

1. Set the TCP_JOIN_PORT_TRY_COUNT property to a positive integer (e.g. 3 or the default) in your hazelcast config/properties.
2. Remove the property entirely so the default value is used.
3. Check any config templating/interpolation that may be rendering an empty string parsed as 0 or a negative number.
4. Restart the node after fixing and verify it joins the cluster via the logs.

Example fix

// before (hazelcast config)
properties:
  hazelcast.tcp.join.port.try.count: 0
// after
properties:
  hazelcast.tcp.join.port.try.count: 3

int tryCount = Integer.parseInt(props.getProperty("hazelcast.tcp.join.port.try.count", "3"));
if (tryCount <= 0) throw new IllegalArgumentException("TCP_JOIN_PORT_TRY_COUNT must be > 0, got " + tryCount);

When it happens

Trigger: Starting a SeaTunnel node whose Hazelcast config sets 'hazelcast.tcp.join.port.try.count' (ClusterProperty.TCP_JOIN_PORT_TRY_COUNT) to 0 or a negative integer; the exception is thrown from the LiteNodeDropOutTcpIpJoiner constructor before the node can join the cluster.

Common situations: Hand-edited hazelcast.yaml/properties where the try-count was set to 0 to 'disable port scanning' without realizing joining then fails; templated configs interpolating an empty or negative value; copy-paste of tuning guides recommending very low values.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• agent.id must be non-empty after resolution.
• input must be defined.
• transport.aes-secret-key-base64 is required when transport.e
• Invalid target address: NULL
• Schema config can not be empty

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