{"record":{"id":"feefefe604d49269","repo":"apache/iceberg","slug":"failed-to-serialize-envelope-key-metadata","errorCode":null,"errorMessage":"Failed to serialize envelope key metadata","messagePattern":"Failed to serialize envelope key metadata","errorType":"exception","errorClass":"UncheckedIOException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/iceberg/encryption/StandardKeyMetadata.java","lineNumber":130,"sourceCode":"    }\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\n  public NativeEncryptionKeyMetadata copyWithLength(long length) {\n    return new StandardKeyMetadata(this, length);\n  }\n\n  @Override\n  public void put(int i, Object v) {\n    switch (i) {\n      case 0:\n        this.encryptionKey = (ByteBuffer) v;","sourceCodeStart":112,"sourceCodeEnd":148,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/encryption/StandardKeyMetadata.java#L112-L148","documentation":"StandardKeyMetadata.buffer() serializes this envelope key metadata (encryption key, AAD prefix, file length) into its Avro-encoded ByteBuffer form using a shared KeyMetadataEncoder. If the underlying Avro encoding raises IOException, it is rethrown as an UncheckedIOException with this message. In practice this indicates a low-level failure in the Avro binary encoding path, not a user-visible data problem.","triggerScenarios":"Calling buffer() on a StandardKeyMetadata (or via castOrParse/EncryptionKeyMetadata API) when the Avro encoder fails internally — e.g. a corrupted/reflectively-mutated internal state or an encoder I/O failure.","commonSituations":"Rarely hit by end users; mostly appears when custom encryption integrations supply non-standard key metadata implementations whose serialized form is incompatible, or when the shared encoder is used concurrently in ways it does not support.","solutions":["Inspect the wrapped IOException cause to identify the actual Avro encoding failure.","Verify the key metadata fields (encryptionKey, aadPrefix) are valid non-null ByteBuffers with correct positions.","Ensure custom EncryptionKeyMetadata implementations are converted through StandardKeyMetadata.castOrParse before encoding.","If reproducible, report the Avro encoder failure to the Iceberg project with the cause stack trace."],"exampleFix":"// before — bare buffer call that may throw unchecked\nByteBuffer buf = keyMetadata.buffer();\n// after — catch the unchecked wrapper and inspect cause\ntry {\n  ByteBuffer buf = keyMetadata.buffer();\n} catch (UncheckedIOException e) {\n  LOG.error(\"key metadata encode failed\", e.getCause());\n  throw e;\n}","handlingStrategy":"try-catch","validationCode":"if (keyMetadata instanceof StandardKeyMetadata) return keyMetadata.buffer();\nByteBuffer b = keyMetadata.buffer();\nif (b == null) throw new IllegalStateException(\"Null key metadata buffer\");\nreturn b;","typeGuard":"boolean isStandard = km instanceof StandardKeyMetadata;","tryCatchPattern":"try {\n  ByteBuffer buf = keyMetadata.buffer();\n} catch (UncheckedIOException e) {\n  throw new IllegalStateException(\"key metadata serialization failed: \" + e.getCause(), e);\n}","preventionTips":["Convert all custom EncryptionKeyMetadata through StandardKeyMetadata.castOrParse before use.","Keep encryptionKey/aadPrefix buffers non-null with valid positions.","Treat buffer() as infallible by contract; investigate any occurrence as a library bug."],"tags":["encryption","serialization","avro","unchecked-io"],"backgroundTag":"json-marshal-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"}