apache/seatunnel · error · OptionValidationException

Invalid secret_key: AES-256 requires exactly 32 bytes, but…

Error message

Invalid secret_key: AES-256 requires exactly 32 bytes, but got %d bytes after Base64 decoding

What it means

After successful Base64 decoding, the secret_key must be exactly 32 bytes for AES-256. Validation rejects any other decoded length (16-byte AES-128 keys, empty keys, truncated Base64) with an OptionValidationException stating the required and actual byte counts.

Solutions

Regenerate with exactly 32 bytes: `openssl rand -base64 32` and verify decoded length is 32.
If you have a 16-byte key and must keep it, note the connector requires AES-256 — pad/derive via a KDF only if both sides agree; otherwise regenerate as 32 bytes.
Base64-decode locally (`base64 -d | wc -c`) to confirm the length before deploying.
Synchronize the corrected key on all sender and receiver nodes.

Example fix

// before
secret_key = "MTIzNDU2Nzg5MGFiY2RlZg==" // decodes to 16 bytes
// after
secret_key = "ASIscmWlnSPjJDvFXT4fzn9WXCFxHqcueqcbfXhz1Ro=" // 32 bytes

Defensive patterns

Strategy: validation

Validate before calling

byte[] keyBytes = Base64.getDecoder().decode(secretKey);
if (keyBytes.length != 32) {
    throw new IllegalArgumentException("AES-256 key must decode to 32 bytes, got " + keyBytes.length);
}

Try / catch

try {
    factory.apply(config);
} catch (OptionValidationException e) {
    log.error("secret_key length invalid: {}", e.getMessage());
}

Prevention

Always generate 32-byte keys (`openssl rand -base64 32`).
Verify with `echo <key> | base64 -d | wc -c` before deploying.
Synchronize key changes across sender and receiver configs simultaneously.

When it happens

Trigger: evaluate() decodes the secret_key and its byte[] length differs from 32 — e.g. a 16-byte AES-128 key, a 24-byte AES-192 key, a key generated with `openssl rand -base64 16`, or a truncated Base64 string.

Common situations: Reusing a key generated for AES-128 from another component; generating a key with a default size other than 32 bytes; copy/paste dropping trailing characters; sender/receiver key lengths drifting apart after a config update.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/945cf4d40e754078. Report an issue: GitHub.

Appendix: source

Thrown at seatunnel-connectors-v2/connector-edge-socket/src/main/java/org/apache/seatunnel/connectors/seatunnel/edgesocket/source/EdgeSocketSourceFactory.java:161

                return true;
            }
            EdgeSocketPacketMode packetMode;
            try {
                packetMode = config.get(EdgeSocketSourceOptions.PACKET_MODE);
            } catch (IllegalArgumentException exception) {
                return true;
            }
            if (packetMode != EdgeSocketPacketMode.PACKET) {
                return true;
            }
            byte[] secretKeyBytes;
            try {
                secretKeyBytes = Base64.getDecoder().decode(secretKey);
            } catch (IllegalArgumentException exception) {
                throw new OptionValidationException("Invalid secret_key: not Base64 encoded");
            }
            if (secretKeyBytes.length != 32) {
                throw new OptionValidationException(
                        "Invalid secret_key: AES-256 requires exactly 32 bytes, "
                                + "but got %d bytes after Base64 decoding",
                        secretKeyBytes.length);
            }
            return true;
        }
    }
}

View on GitHub (pinned to cf67b549a7)