{"record":{"id":"373c4b54230a0c3e","repo":"apache/flink","slug":"the-desired-number-of-splits-must-be-positive-or","errorCode":null,"errorMessage":"The desired number of splits must be positive or -1 (= don't care).","messagePattern":"The desired number of splits must be positive or -1 \\(= don't care\\)\\.","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"flink-core/src/main/java/org/apache/flink/api/common/io/FileInputFormat.java","lineNumber":334,"sourceCode":"    public long getMinSplitSize() {\n        return minSplitSize;\n    }\n\n    public void setMinSplitSize(long minSplitSize) {\n        if (minSplitSize < 0) {\n            throw new IllegalArgumentException(\"The minimum split size cannot be negative.\");\n        }\n\n        this.minSplitSize = minSplitSize;\n    }\n\n    public int getNumSplits() {\n        return numSplits;\n    }\n\n    public void setNumSplits(int numSplits) {\n        if (numSplits < -1 || numSplits == 0) {\n            throw new IllegalArgumentException(\n                    \"The desired number of splits must be positive or -1 (= don't care).\");\n        }\n\n        this.numSplits = numSplits;\n    }\n\n    public long getOpenTimeout() {\n        return openTimeout;\n    }\n\n    public void setOpenTimeout(long openTimeout) {\n        if (openTimeout < 0) {\n            throw new IllegalArgumentException(\n                    \"The timeout for opening the input splits must be positive or zero (= infinite).\");\n        }\n        this.openTimeout = openTimeout;\n    }\n","sourceCodeStart":316,"sourceCodeEnd":352,"githubUrl":"https://github.com/apache/flink/blob/2f3c205e9266cb30240eb7f4fdab15cad629a70f/flink-core/src/main/java/org/apache/flink/api/common/io/FileInputFormat.java#L316-L352","documentation":"numSplits is the desired number of input splits. The format accepts any positive integer, and -1 as a 'don't care' sentinel (let the framework decide). Zero and values below -1 are invalid because they cannot express a real split count, so FileInputFormat.setNumSplits rejects them with IllegalArgumentException.","triggerScenarios":"Calling format.setNumSplits(0) or any value < -1 (e.g. -2).","commonSituations":"Passing 0 intending 'automatic' (the sentinel is -1, not 0); computing numSplits from parallelism that resolved to 0; misreading documentation and using -2 as 'unlimited'.","solutions":["Pass a positive integer for an explicit count, or -1 to let the framework decide.","Coerce invalid values: numSplits = desired > 0 ? desired : -1.","Do not call setNumSplits if you want the default (-1 / framework-decided)."],"exampleFix":"// before\nformat.setNumSplits(parallelism); // parallelism == 0 -> throws\n\n// after\nint n = parallelism > 0 ? parallelism : -1;\nformat.setNumSplits(n);","handlingStrategy":"validation","validationCode":"int n = (numSplits > 0) ? numSplits : -1;\nformat.setNumSplits(n);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Remember -1 (not 0) is the 'don't care' sentinel.","Coerce 0/negative-below-minus-one to -1 before calling.","Derive numSplits from a validated positive parallelism."],"tags":["input-format","num-splits","validation","illegal-argument"],"backgroundTag":null,"analyzedSha":"2f3c205e9266cb30240eb7f4fdab15cad629a70f","analyzedAt":"2026-08-14T08:48:24.518Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}