apache/seatunnel · error · IllegalArgumentException

Subtask ID ${subTaskId} is out of server id range ${this}, p

Error message

Subtask ID ${subTaskId} is out of server id range ${this}, please adjust the server id range to make the number of server id larger than the source parallelism.

What it means

ServerIdRange.getServerId maps a source subtask index to a unique MySQL server id within the configured range. If the subtask id exceeds the number of ids available in the range, an IllegalArgumentException is thrown: MySQL requires each parallel reader to impersonate a distinct replica server id, so the range must be at least as large as the parallelism.

Source

Thrown at seatunnel-connectors-v2/connector-cdc/connector-cdc-mysql/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/mysql/config/ServerIdRange.java:57

    private final long endServerId;

    public ServerIdRange(long startServerId, long endServerId) {
        this.startServerId = startServerId;
        this.endServerId = endServerId;
    }

    public long getStartServerId() {
        return startServerId;
    }

    public long getEndServerId() {
        return endServerId;
    }

    public long getServerId(int subTaskId) {
        checkArgument(subTaskId >= 0, "Subtask ID %s shouldn't be a negative number.", subTaskId);
        if ((long) subTaskId > getNumberOfServerIds()) {
            throw new IllegalArgumentException(
                    String.format(
                            "Subtask ID %s is out of server id range %s, "
                                    + "please adjust the server id range to "
                                    + "make the number of server id larger than "
                                    + "the source parallelism.",
                            subTaskId, this));
        }
        return startServerId + subTaskId;
    }

    public long getNumberOfServerIds() {
        return endServerId - startServerId + 1L;
    }

    @Override
    public String toString() {
        if (startServerId == endServerId) {
            return String.valueOf(startServerId);

View on GitHub (pinned to cf67b549a7)

Solutions

1. Widen the server-id range so its size >= source parallelism (e.g. server-id = 5400-6400 for parallelism 1000).
2. Reduce the source parallelism to fit within the existing range.
3. Verify the configured range does not overlap other active replicas' server ids while widening.
4. Use 5401-5500 style explicit ranges per job to avoid collisions between concurrent CDC jobs.

Example fix

// before
server-id = 5400-5410   # parallelism = 16
// after
server-id = 5400-5499   # 100 ids >= parallelism 16

// Ensure range size >= parallelism before submitting job
ServerIdRange range = ServerIdRange.from(conf);
if (parallelism > range.getNumberOfServerIds()) {
    throw new IllegalArgumentException("Widen server-id range to at least " + parallelism);
}

try { range.getServerId(subtaskId); } catch (IllegalArgumentException e) { /* reduce parallelism or widen range */ throw e; }

When it happens

Trigger: Calling getServerId(subTaskId) when source parallelism exceeds the size of the server-id range (e.g. server-id=5400-5410 with parallelism 16), so subtask ids 11+ have no id to claim.

Common situations: Increasing job parallelism after initially configuring a narrow server-id range; forgetting to configure server-id at all so a tiny default range is used; multi-parallel CDC jobs on single-MPP engines.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• System or JVM property '<property>' is already defined, but
• The server id range should be syntax like '5400-5500', but g
• The server id ${serverIdValue} is not a valid numeric.
• Single file mode is not supported when file_name_expression
• Connector used GTIDs previously, but MySQL does not know of

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