apache/seatunnel · error · EdgeSocketConnectorException

PACKET_AES_KEY_MISSING

PACKET_AES_KEY_MISSING

Error message

Missing secret_key when packet encryption is AES_GCM

What it means

When an incoming packet declares AES_GCM encryption, decodeEncryption() requires the connector config to carry the shared secret. If config.getSecretKeyBytes() is null or empty, it throws EdgeSocketConnectorException with code PACKET_AES_KEY_MISSING. Without the key, AES-GCM packets cannot be decrypted, so the consumer fails fast rather than emitting undecryptable records.

Solutions

Add or fix the secret_key config option on the edge-socket consumer so it matches the producer.
Verify the key derivation produces non-empty bytes (check secret_key is not blank).
If encryption is not intended, set the producer's encryption to 'none'.

Example fix

// before
# (secret_key absent)
// after
secret_key = "shared-hex-or-base64-key"

Defensive patterns

Strategy: validation

Validate before calling

if (config.getSecretKeyBytes() == null || config.getSecretKeyBytes().length == 0) {
    throw new IllegalStateException("secret_key must be set when packet encryption is AES_GCM");
}

Try / catch

try {
    byte[] payload = decryptedPayload(payloadBytes, packet, encryptionType);
} catch (EdgeSocketConnectorException e) {
    if (e.getErrorCode() == EdgeSocketConnectorErrorCode.PACKET_AES_KEY_MISSING) {
        // fail fast: load secret_key into config before retrying
    }
}

Prevention

Always pair encryption=aes_gcm with a non-empty secret_key in every environment's config.
Add a config pre-flight check that secret_key is present when encryption is enabled.
Use config management so the key cannot be silently dropped between deploys.

When it happens

Trigger: decodeEncryption() processes an AES_GCM-encrypted packet while the consumer's config lacks the secret_key option (missing, empty, or failed to derive key bytes).

Common situations: Producer enables encryption but the consumer config was not updated with the matching secret_key, blank secret_key value, or a config loading step that dropped the field.

Understand the failure class

Background: "API key is required" / "API key not found" / "No API key was set": the missing-api-key error family across 16 libraries — this error's family across 16 libraries.

Related errors

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

Appendix: source

Thrown at seatunnel-connectors-v2/connector-edge-socket/src/main/java/org/apache/seatunnel/connectors/seatunnel/edgesocket/serialize/record/EdgeSocketPacketRecordDeserializer.java:98

     * @param payloadBytes base64-decoded payload bytes from packet
     * @param packet ingress packet metadata
     * @param encryptionType resolved encryption type
     * @return decrypted payload bytes (or original bytes when encryption is NONE)
     */
    private byte[] decodeEncryption(
            byte[] payloadBytes,
            EdgeSocketIngressPacket packet,
            EdgeSocketEncryptionType encryptionType) {
        if (encryptionType == EdgeSocketEncryptionType.NONE) {
            return payloadBytes;
        }
        if (encryptionType != EdgeSocketEncryptionType.AES_GCM) {
            throw new EdgeSocketConnectorException(
                    EdgeSocketConnectorErrorCode.PACKET_UNSUPPORTED_ENCRYPTION,
                    "Unsupported packet encryption type: " + encryptionType);
        }
        if (config.getSecretKeyBytes() == null || config.getSecretKeyBytes().length == 0) {
            throw new EdgeSocketConnectorException(
                    EdgeSocketConnectorErrorCode.PACKET_AES_KEY_MISSING,
                    "Missing secret_key when packet encryption is AES_GCM");
        }
        if (packet.getIv() == null || packet.getIv().isEmpty()) {
            throw new EdgeSocketConnectorException(
                    EdgeSocketConnectorErrorCode.PACKET_DECODE_ERROR,
                    "Missing iv in AES_GCM packet");
        }
        try {
            byte[] iv = Base64.getDecoder().decode(packet.getIv());
            Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
            SecretKeySpec key = new SecretKeySpec(config.getSecretKeyBytes(), "AES");
            cipher.init(
                    Cipher.DECRYPT_MODE, key, new GCMParameterSpec(AES_GCM_TAG_LENGTH_BITS, iv));
            return cipher.doFinal(payloadBytes);
        } catch (GeneralSecurityException securityException) {
            throw new EdgeSocketConnectorException(
                    EdgeSocketConnectorErrorCode.PACKET_DECODE_ERROR,

View on GitHub (pinned to cf67b549a7)