apache/iceberg · error · IllegalStateException

Null key metadata buffer

Error message

Null key metadata buffer

What it means

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.

Source

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

  @Override
  public ByteBuffer aadPrefix() {
    return aadPrefix;
  }

  @Override
  public Long fileLength() {
    return fileLength;
  }

  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) {

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Ensure the KeyMetadata implementation returns a valid serialized buffer from buffer()
2. Pass actual StandardKeyMetadata instances instead of custom implementations
3. Fix the custom KeyMetadata class to serialize its content when buffer() is called

Example fix

// before
class LazyKeyMetadata implements KeyMetadata { public ByteBuffer buffer() { return null; } }
// after
class LazyKeyMetadata implements KeyMetadata {
  public ByteBuffer buffer() { return serialized(); } // always return encoded bytes
}

if (keyMetadata == null || (keyMetadata.buffer() == null && !(keyMetadata instanceof StandardKeyMetadata))) {
  throw new IllegalArgumentException("Key metadata has no buffer and is not StandardKeyMetadata");
}

boolean isParsable(KeyMetadata km) { return km instanceof StandardKeyMetadata || km.buffer() != null; }

try { return StandardKeyMetadata.castOrParse(km); }
catch (IllegalStateException e) { /* null buffer: obtain metadata from source */ throw e; }

When it happens

Trigger: 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.

Common situations: Custom KeyMetadata implementations that lazily serialize (returning null buffer) passed into code expecting standard metadata; metadata objects left uninitialized in third-party encryption code.

Related errors

• Failed to read the version byte
• Version byte - end of stream reached
• Cannot resolve schema for version: ${writeSchemaVersion}
• Failed to parse envelope encryption metadata
• Failed to close encryption manager

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