{"record":{"id":"5aefcaa1b0e9c4a6","repo":"apache/seatunnel","slug":"clusterproperty-tcp-join-port-try-count-must-be","errorCode":null,"errorMessage":"${ClusterProperty.TCP_JOIN_PORT_TRY_COUNT} must be greater than zero! Current value: ${tryCount}","messagePattern":"(.+?) must be greater than zero! Current value: (.+?)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"critical","filePath":"seatunnel-engine/seatunnel-engine-server/src/main/java/org/apache/seatunnel/engine/server/joiner/LiteNodeDropOutTcpIpJoiner.java","lineNumber":70,"sourceCode":"import static com.hazelcast.internal.cluster.impl.ClusterServiceImpl.SERVICE_NAME;\nimport static com.hazelcast.internal.util.EmptyStatement.ignore;\nimport static com.hazelcast.internal.util.FutureUtil.RETHROW_EVERYTHING;\nimport static com.hazelcast.internal.util.FutureUtil.returnWithDeadline;\n\npublic class LiteNodeDropOutTcpIpJoiner extends TcpIpJoiner {\n\n    private static final long JOIN_RETRY_WAIT_TIME = 1000L;\n    private static final int MASTERSHIP_CLAIM_TIMEOUT = 10;\n\n    private final int maxPortTryCount;\n    private volatile boolean claimingMastership;\n    private final JoinConfig joinConfig;\n\n    public LiteNodeDropOutTcpIpJoiner(Node node) {\n        super(node);\n        int tryCount = node.getProperties().getInteger(ClusterProperty.TCP_JOIN_PORT_TRY_COUNT);\n        if (tryCount <= 0) {\n            throw new IllegalArgumentException(\n                    String.format(\n                            \"%s must be greater than zero! Current value: %d\",\n                            ClusterProperty.TCP_JOIN_PORT_TRY_COUNT, tryCount));\n        }\n        maxPortTryCount = tryCount;\n        joinConfig = getActiveMemberNetworkConfig(config).getJoin();\n    }\n\n    @Override\n    public boolean isClaimingMastership() {\n        return claimingMastership;\n    }\n\n    private int getConnTimeoutSeconds() {\n        return joinConfig.getTcpIpConfig().getConnectionTimeoutSeconds();\n    }\n\n    @Override","sourceCodeStart":52,"sourceCodeEnd":88,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-engine/seatunnel-engine-server/src/main/java/org/apache/seatunnel/engine/server/joiner/LiteNodeDropOutTcpIpJoiner.java#L52-L88","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set the TCP_JOIN_PORT_TRY_COUNT property to a positive integer (e.g. 3 or the default) in your hazelcast config/properties.","Remove the property entirely so the default value is used.","Check any config templating/interpolation that may be rendering an empty string parsed as 0 or a negative number.","Restart the node after fixing and verify it joins the cluster via the logs."],"exampleFix":"// before (hazelcast config)\nproperties:\n  hazelcast.tcp.join.port.try.count: 0\n// after\nproperties:\n  hazelcast.tcp.join.port.try.count: 3","handlingStrategy":"validation","validationCode":"int tryCount = Integer.parseInt(props.getProperty(\"hazelcast.tcp.join.port.try.count\", \"3\"));\nif (tryCount <= 0) throw new IllegalArgumentException(\"TCP_JOIN_PORT_TRY_COUNT must be > 0, got \" + tryCount);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never set TCP_JOIN_PORT_TRY_COUNT to 0 or negative values in hazelcast configs.","Validate templated config values after interpolation before starting nodes.","Keep the property at its default unless you have a tested reason to change it."],"tags":["config","cluster-join","startup","hazelcast"],"backgroundTag":"invalid-config-value","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}