{"record":{"id":"7e510f539c8f4bd0","repo":"apache/iceberg","slug":"null-key-metadata-buffer","errorCode":null,"errorMessage":"Null key metadata buffer","messagePattern":"Null key metadata buffer","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/iceberg/encryption/StandardKeyMetadata.java","lineNumber":111,"sourceCode":"  @Override\n  public ByteBuffer aadPrefix() {\n    return aadPrefix;\n  }\n\n  @Override\n  public Long fileLength() {\n    return fileLength;\n  }\n\n  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) {","sourceCodeStart":93,"sourceCodeEnd":129,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/encryption/StandardKeyMetadata.java#L93-L129","documentation":"StandardKeyMetadata.castOrParse first tries to treat the input as a StandardKeyMetadata instance; otherwise it reads its buffer() and throws IllegalStateException if that buffer is null. Key metadata that is neither a StandardKeyMetadata nor backed by a parseable byte buffer cannot be converted.","triggerScenarios":"Calling castOrParse with a KeyMetadata implementation whose buffer() returns null — e.g. a custom KeyMetadata that holds no serialized bytes and is not itself a StandardKeyMetadata.","commonSituations":"Custom KeyMetadata implementations that lazily serialize (returning null buffer) passed into code expecting standard metadata; metadata objects left uninitialized in third-party encryption code.","solutions":["Ensure the KeyMetadata implementation returns a valid serialized buffer from buffer()","Pass actual StandardKeyMetadata instances instead of custom implementations","Fix the custom KeyMetadata class to serialize its content when buffer() is called"],"exampleFix":"// before\nclass LazyKeyMetadata implements KeyMetadata { public ByteBuffer buffer() { return null; } }\n// after\nclass LazyKeyMetadata implements KeyMetadata {\n  public ByteBuffer buffer() { return serialized(); } // always return encoded bytes\n}","handlingStrategy":"validation","validationCode":"if (keyMetadata == null || (keyMetadata.buffer() == null && !(keyMetadata instanceof StandardKeyMetadata))) {\n  throw new IllegalArgumentException(\"Key metadata has no buffer and is not StandardKeyMetadata\");\n}","typeGuard":"boolean isParsable(KeyMetadata km) { return km instanceof StandardKeyMetadata || km.buffer() != null; }","tryCatchPattern":"try { return StandardKeyMetadata.castOrParse(km); }\ncatch (IllegalStateException e) { /* null buffer: obtain metadata from source */ throw e; }","preventionTips":["Ensure custom KeyMetadata implementations always return encoded bytes from buffer()","Pass StandardKeyMetadata instances where possible","Never leave key metadata uninitialized before handing it to Iceberg APIs"],"tags":["encryption","null","deserialization"],"backgroundTag":"null-argument","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"}