apache/flink · error · IllegalArgumentException

Entropy length must be >= 0 when entropy injection key is se

Error message

Entropy length must be >= 0 when entropy injection key is set

What it means

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.

Source

Thrown at flink-filesystems/flink-s3-fs-native/src/main/java/org/apache/flink/fs/s3native/NativeS3FileSystem.java:153

        this.entropyInjectionKey = entropyInjectionKey;
        this.entropyLength = entropyLength;
        this.localTmpDir = localTmpDir;
        this.s3uploadPartSize = s3uploadPartSize;
        this.maxConcurrentUploadsPerStream = maxConcurrentUploadsPerStream;
        this.useAsyncOperations = useAsyncOperations;
        this.readBufferSize = readBufferSize;
        this.fsCloseTimeout = fsCloseTimeout;
        this.s3AccessHelper =
                new NativeS3ObjectOperations(
                        clientProvider.getS3Client(),
                        clientProvider.getTransferManager(),
                        bucketName,
                        useAsyncOperations,
                        clientProvider.getEncryptionConfig());
        this.bulkCopyHelper = bulkCopyHelper;

        if (entropyInjectionKey != null && entropyLength <= 0) {
            throw new IllegalArgumentException(
                    "Entropy length must be >= 0 when entropy injection key is set");
        }

        LOG.info(
                "Created Native S3 FileSystem for bucket: {}, entropy injection: {}, bulk copy: {}, read buffer: {} KB",
                bucketName,
                entropyInjectionKey != null,
                bulkCopyHelper != null,
                readBufferSize / 1024);
    }

    @VisibleForTesting
    Duration getFsCloseTimeout() {
        return fsCloseTimeout;
    }

    @VisibleForTesting
    S3ClientProvider getClientProvider() {

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Set the entropy length to a positive value, e.g. s3.entropy.length: 4, whenever an entropy injection key is configured.
2. Or remove the entropy injection key entirely if entropy injection is not needed (then the length check is skipped).
3. Verify both options come from the same config scope after template/variable substitution.

Example fix

# before
s3.entropy.key: __entropy__
# s3.entropy.length missing -> IllegalArgumentException

# after
s3.entropy.key: __entropy__
s3.entropy.length: 4

// validate before constructing/configuring the filesystem
String key = conf.getString("s3.entropy.key", null);
long length = conf.getLong("s3.entropy.length", -1);
if (key != null && length <= 0) {
    throw new IllegalArgumentException("s3.entropy.length must be > 0 when s3.entropy.key is set");
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Invalid assume-role.session-duration '%s' for bucket '%s'. M
• Invalid path-style-access '%s' for bucket '%s'. Must be 'tru
• Invalid S3 URI: missing or empty bucket name in URI: {}
• Not allowed configuration change(s) were detected:\n - {erro
• At least one trigger condition must be configured.

AI-assisted analysis of apache/flink@2f3c205e92 (2026-08-14). Data as JSON: /api/errors/85cb8182ae2b740c. Report an issue: GitHub.