{"record":{"id":"3f91d3bccf2e7b64","repo":"apache/seatunnel","slug":"subtask-id-subtaskid-is-out-of-server-id-range","errorCode":null,"errorMessage":"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.","messagePattern":"Subtask ID (.+?) is out of server id range (.+?), please adjust the server id range to make the number of server id larger than the source parallelism\\.","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"seatunnel-connectors-v2/connector-cdc/connector-cdc-mysql/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/mysql/config/ServerIdRange.java","lineNumber":57,"sourceCode":"    private final long endServerId;\n\n    public ServerIdRange(long startServerId, long endServerId) {\n        this.startServerId = startServerId;\n        this.endServerId = endServerId;\n    }\n\n    public long getStartServerId() {\n        return startServerId;\n    }\n\n    public long getEndServerId() {\n        return endServerId;\n    }\n\n    public long getServerId(int subTaskId) {\n        checkArgument(subTaskId >= 0, \"Subtask ID %s shouldn't be a negative number.\", subTaskId);\n        if ((long) subTaskId > getNumberOfServerIds()) {\n            throw new IllegalArgumentException(\n                    String.format(\n                            \"Subtask ID %s is out of server id range %s, \"\n                                    + \"please adjust the server id range to \"\n                                    + \"make the number of server id larger than \"\n                                    + \"the source parallelism.\",\n                            subTaskId, this));\n        }\n        return startServerId + subTaskId;\n    }\n\n    public long getNumberOfServerIds() {\n        return endServerId - startServerId + 1L;\n    }\n\n    @Override\n    public String toString() {\n        if (startServerId == endServerId) {\n            return String.valueOf(startServerId);","sourceCodeStart":39,"sourceCodeEnd":75,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-cdc/connector-cdc-mysql/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/mysql/config/ServerIdRange.java#L39-L75","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Widen the server-id range so its size >= source parallelism (e.g. server-id = 5400-6400 for parallelism 1000).","Reduce the source parallelism to fit within the existing range.","Verify the configured range does not overlap other active replicas' server ids while widening.","Use 5401-5500 style explicit ranges per job to avoid collisions between concurrent CDC jobs."],"exampleFix":"// before\nserver-id = 5400-5410   # parallelism = 16\n// after\nserver-id = 5400-5499   # 100 ids >= parallelism 16","handlingStrategy":"validation","validationCode":"// Ensure range size >= parallelism before submitting job\nServerIdRange range = ServerIdRange.from(conf);\nif (parallelism > range.getNumberOfServerIds()) {\n    throw new IllegalArgumentException(\"Widen server-id range to at least \" + parallelism);\n}","typeGuard":null,"tryCatchPattern":"try { range.getServerId(subtaskId); } catch (IllegalArgumentException e) { /* reduce parallelism or widen range */ throw e; }","preventionTips":["Always size server-id range >= max expected parallelism.","Keep per-job server-id ranges disjoint to avoid replica id collisions.","Re-check the range whenever you scale parallelism up."],"tags":["mysql","server-id","parallelism","configuration"],"backgroundTag":"value-out-of-range","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}