{"record":{"id":"18efb7746b0131ec","repo":"apache/iceberg","slug":"failed-to-parse-envelope-encryption-metadata","errorCode":null,"errorMessage":"Failed to parse envelope encryption metadata","messagePattern":"Failed to parse envelope encryption metadata","errorType":"exception","errorClass":"UncheckedIOException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/iceberg/encryption/StandardKeyMetadata.java","lineNumber":121,"sourceCode":"  static StandardKeyMetadata castOrParse(EncryptionKeyMetadata keyMetadata) {\n    if (keyMetadata instanceof StandardKeyMetadata) {\n      return (StandardKeyMetadata) keyMetadata;\n    }\n\n    ByteBuffer kmBuffer = keyMetadata.buffer();\n\n    if (kmBuffer == null) {\n      throw new IllegalStateException(\"Null key metadata buffer\");\n    }\n\n    return parse(kmBuffer);\n  }\n\n  static StandardKeyMetadata parse(ByteBuffer buffer) {\n    try {\n      return KEY_METADATA_DECODER.decode(buffer);\n    } catch (IOException e) {\n      throw new UncheckedIOException(\"Failed to parse envelope encryption metadata\", e);\n    }\n  }\n\n  @Override\n  public ByteBuffer buffer() {\n    try {\n      return KEY_METADATA_ENCODER.encode(this);\n    } catch (IOException e) {\n      throw new UncheckedIOException(\"Failed to serialize envelope key metadata\", e);\n    }\n  }\n\n  @Override\n  public EncryptionKeyMetadata copy() {\n    return new StandardKeyMetadata(this, null);\n  }\n\n  @Override","sourceCodeStart":103,"sourceCodeEnd":139,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/encryption/StandardKeyMetadata.java#L103-L139","documentation":"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).","triggerScenarios":"Calling StandardKeyMetadata.parse (or castOrParse on a foreign KeyMetadata) with a ByteBuffer whose contents fail Avro decoding — corrupted, truncated, or non-key-metadata bytes.","commonSituations":"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.","solutions":["Inspect the chained cause (getCause) to find the exact Avro decode failure","Re-derive or re-read the key metadata from the source file; rewrite if corrupt","Verify buffer position/limit (duplicate() before use) so the full metadata blob is passed"],"exampleFix":"// before\nparse(sliceOf(buffer, badOffset)); // UncheckedIOException\n// after\nparse(buffer.duplicate().position(0)); // full, correctly positioned metadata blob","handlingStrategy":"validation","validationCode":"if (buffer == null || buffer.remaining() < 2) {\n  throw new IllegalArgumentException(\"Key metadata buffer too small to be valid\");\n}","typeGuard":null,"tryCatchPattern":"try { return StandardKeyMetadata.parse(buffer); }\ncatch (UncheckedIOException e) { throw new IllegalStateException(\"Corrupt key metadata\", e.getCause()); }","preventionTips":["Pass buffer.duplicate() positioned at the metadata start, never a shared mutated buffer","Verify data file integrity (checksums) when key metadata fails to parse","Keep producer and consumer Iceberg versions compatible"],"tags":["encryption","deserialization","avro","corrupt-data"],"backgroundTag":"protobuf-unmarshal-failed","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}