{"record":{"id":"85cb8182ae2b740c","repo":"apache/flink","slug":"entropy-length-must-be-0-when-entropy-injection-85cb81","errorCode":null,"errorMessage":"Entropy length must be >= 0 when entropy injection key is set","messagePattern":"Entropy length must be >= 0 when entropy injection key is set","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"flink-filesystems/flink-s3-fs-native/src/main/java/org/apache/flink/fs/s3native/NativeS3FileSystem.java","lineNumber":153,"sourceCode":"        this.entropyInjectionKey = entropyInjectionKey;\n        this.entropyLength = entropyLength;\n        this.localTmpDir = localTmpDir;\n        this.s3uploadPartSize = s3uploadPartSize;\n        this.maxConcurrentUploadsPerStream = maxConcurrentUploadsPerStream;\n        this.useAsyncOperations = useAsyncOperations;\n        this.readBufferSize = readBufferSize;\n        this.fsCloseTimeout = fsCloseTimeout;\n        this.s3AccessHelper =\n                new NativeS3ObjectOperations(\n                        clientProvider.getS3Client(),\n                        clientProvider.getTransferManager(),\n                        bucketName,\n                        useAsyncOperations,\n                        clientProvider.getEncryptionConfig());\n        this.bulkCopyHelper = bulkCopyHelper;\n\n        if (entropyInjectionKey != null && entropyLength <= 0) {\n            throw new IllegalArgumentException(\n                    \"Entropy length must be >= 0 when entropy injection key is set\");\n        }\n\n        LOG.info(\n                \"Created Native S3 FileSystem for bucket: {}, entropy injection: {}, bulk copy: {}, read buffer: {} KB\",\n                bucketName,\n                entropyInjectionKey != null,\n                bulkCopyHelper != null,\n                readBufferSize / 1024);\n    }\n\n    @VisibleForTesting\n    Duration getFsCloseTimeout() {\n        return fsCloseTimeout;\n    }\n\n    @VisibleForTesting\n    S3ClientProvider getClientProvider() {","sourceCodeStart":135,"sourceCodeEnd":171,"githubUrl":"https://github.com/apache/flink/blob/2f3c205e9266cb30240eb7f4fdab15cad629a70f/flink-filesystems/flink-s3-fs-native/src/main/java/org/apache/flink/fs/s3native/NativeS3FileSystem.java#L135-L171","documentation":"NativeS3FileSystem's constructor requires that when an entropy injection key is configured (used to spread writes across key prefixes), the entropy length is a positive number. entropyLength <= 0 with a non-null key makes entropy key substring replacement impossible, so construction fails fast with IllegalArgumentException.","triggerScenarios":"Creating the filesystem with s3.entropy.key set but s3.entropy.length unset/zero/negative — e.g. flink-conf defines fs.s3.entropy-key without fs.s3.entropy-length, or the factory passes a default of 0.","commonSituations":"Copy-pasting partial entropy configuration from docs; older Flink versions where entropy length had different option names; programmatic FileSystem creation that passes the key but forgets the length.","solutions":["Set the entropy length to a positive value, e.g. s3.entropy.length: 4, whenever an entropy injection key is configured.","Or remove the entropy injection key entirely if entropy injection is not needed (then the length check is skipped).","Verify both options come from the same config scope after template/variable substitution."],"exampleFix":"# before\ns3.entropy.key: __entropy__\n# s3.entropy.length missing -> IllegalArgumentException\n\n# after\ns3.entropy.key: __entropy__\ns3.entropy.length: 4","handlingStrategy":"validation","validationCode":"// validate before constructing/configuring the filesystem\nString key = conf.getString(\"s3.entropy.key\", null);\nlong length = conf.getLong(\"s3.entropy.length\", -1);\nif (key != null && length <= 0) {\n    throw new IllegalArgumentException(\"s3.entropy.length must be > 0 when s3.entropy.key is set\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Set entropy key and entropy length together, always as a pair.","A typical length is 4 (16 chars of base-16 entropy in the key placeholder).","If entropy injection is not needed, remove both options."],"tags":["s3","configuration","entropy-injection","validation"],"backgroundTag":null,"analyzedSha":"2f3c205e9266cb30240eb7f4fdab15cad629a70f","analyzedAt":"2026-08-14T08:48:24.518Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}