apache/iceberg · error · UncheckedIOException

Failed to parse envelope encryption metadata

Error message

Failed to parse envelope encryption metadata

What it means

StandardKeyMetadata.parse decodes a ByteBuffer into StandardKeyMetadata via KeyMetadataDecoder and wraps any IOException in an UncheckedIOException. It indicates the buffer's bytes are not decodable envelope encryption key metadata (corrupt, truncated, or wrong format).

Source

Thrown at core/src/main/java/org/apache/iceberg/encryption/StandardKeyMetadata.java:121

  static StandardKeyMetadata castOrParse(EncryptionKeyMetadata keyMetadata) {
    if (keyMetadata instanceof StandardKeyMetadata) {
      return (StandardKeyMetadata) keyMetadata;
    }

    ByteBuffer kmBuffer = keyMetadata.buffer();

    if (kmBuffer == null) {
      throw new IllegalStateException("Null key metadata buffer");
    }

    return parse(kmBuffer);
  }

  static StandardKeyMetadata parse(ByteBuffer buffer) {
    try {
      return KEY_METADATA_DECODER.decode(buffer);
    } catch (IOException e) {
      throw new UncheckedIOException("Failed to parse envelope encryption metadata", e);
    }
  }

  @Override
  public ByteBuffer buffer() {
    try {
      return KEY_METADATA_ENCODER.encode(this);
    } catch (IOException e) {
      throw new UncheckedIOException("Failed to serialize envelope key metadata", e);
    }
  }

  @Override
  public EncryptionKeyMetadata copy() {
    return new StandardKeyMetadata(this, null);
  }

  @Override

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Inspect the chained cause (getCause) to find the exact Avro decode failure
2. Re-derive or re-read the key metadata from the source file; rewrite if corrupt
3. Verify buffer position/limit (duplicate() before use) so the full metadata blob is passed

Example fix

// before
parse(sliceOf(buffer, badOffset)); // UncheckedIOException
// after
parse(buffer.duplicate().position(0)); // full, correctly positioned metadata blob

if (buffer == null || buffer.remaining() < 2) {
  throw new IllegalArgumentException("Key metadata buffer too small to be valid");
}

try { return StandardKeyMetadata.parse(buffer); }
catch (UncheckedIOException e) { throw new IllegalStateException("Corrupt key metadata", e.getCause()); }

When it happens

Trigger: Calling StandardKeyMetadata.parse (or castOrParse on a foreign KeyMetadata) with a ByteBuffer whose contents fail Avro decoding — corrupted, truncated, or non-key-metadata bytes.

Common situations: Reading key metadata from a corrupted encrypted data file; passing buffers that were sliced/positioned incorrectly so the decoder reads garbage; mixing metadata formats between libraries.

Understand the failure class

Background: "cannot parse invalid wire-format data", "cannot unmarshal", "failed unmarshalling": protobuf unmarshal errors explained — this error's family across 10 libraries.

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Avro does not support file encryption keys
• Avro does not support AAD prefix
• Failed to read next record
• Decoding datum failed
• Failed to read the version byte

AI-assisted analysis of apache/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/18efb7746b0131ec. Report an issue: GitHub.