{"record":{"id":"febd0123bde13ee0","repo":"apache/seatunnel","slug":"azure-queue-storage-source-expects-exactly-one-sou","errorCode":null,"errorMessage":"Azure Queue Storage source expects exactly one source split","messagePattern":"Azure Queue Storage source expects exactly one source split","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"seatunnel-connectors-v2/connector-azure-queue-storage/src/main/java/org/apache/seatunnel/connectors/seatunnel/azure/queue/source/AzureQueueStorageSourceReader.java","lineNumber":142,"sourceCode":"                        \"Failed to process Azure Queue Storage message \" + message.getMessageId(),\n                        e);\n            }\n        }\n        checkVisibilityRenewalFailure();\n    }\n\n    @Override\n    public List<SingleSplit> snapshotState(long checkpointId) {\n        synchronized (acknowledgementLock) {\n            pendingAcknowledgements.put(checkpointId, new ArrayList<>(unacknowledgedMessages));\n        }\n        return Collections.singletonList(new SingleSplit(null));\n    }\n\n    @Override\n    public void addSplits(List<SingleSplit> splits) {\n        if (splits.size() != 1) {\n            throw new IllegalArgumentException(\n                    \"Azure Queue Storage source expects exactly one source split\");\n        }\n        if (splitAssigned) {\n            return;\n        }\n\n        receiver = receiverFactory.create();\n        visibilityRenewalExecutor =\n                Executors.newSingleThreadScheduledExecutor(\n                        runnable -> {\n                            Thread thread = new Thread(runnable, \"azure-queue-visibility-renewal\");\n                            thread.setDaemon(true);\n                            return thread;\n                        });\n        long renewalIntervalSeconds = Math.max(1L, config.getVisibilityTimeoutSeconds() / 3L);\n        visibilityRenewalExecutor.scheduleWithFixedDelay(\n                this::renewVisibilitySafely,\n                renewalIntervalSeconds,","sourceCodeStart":124,"sourceCodeEnd":160,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-azure-queue-storage/src/main/java/org/apache/seatunnel/connectors/seatunnel/azure/queue/source/AzureQueueStorageSourceReader.java#L124-L160","documentation":"AzureQueueStorageSourceReader.addSplits() enforces the single-split invariant: this connector reads one queue per reader, so exactly one split must be delivered. Receiving zero or multiple splits throws IllegalArgumentException.","triggerScenarios":"The split enumerator/assignSplit path delivers a list whose size != 1 to addSplits() — e.g. a parallelism/enum bug, custom code, or framework passing an empty list.","commonSituations":"Running with misconfigured parallelism assumptions, internal connector bugs, or embedding the connector with a custom enumerator that generates multiple SingleSplits.","solutions":["Ensure source parallelism matches the single-split enumerator (parallelism 1 for a single queue)","Update the connector to a version fixing split enumeration","If custom, fix the enumerator to return exactly one SingleSplit"],"exampleFix":"// before (custom enumerator)\nreturn Arrays.asList(new SingleSplit(null), new SingleSplit(null));\n// after\nreturn Collections.singletonList(new SingleSplit(null));","handlingStrategy":"try-catch","validationCode":"if (splits.size() != 1) throw new IllegalStateException(\"expected exactly one split\");","typeGuard":null,"tryCatchPattern":"try {\n    reader.addSplits(splits);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"exactly one source split\")) {\n        LOG.error(\"Split enumeration returned {} splits; expected 1\", splits.size());\n    }\n    throw e;\n}","preventionTips":["Use the connector's built-in enumerator unchanged","Keep source parallelism consistent with single-split design","Pin to a connector version with known-good split enumeration"],"tags":["split","internal-invariant","azure"],"backgroundTag":"internal-invariant-violation","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"}