apache/iceberg · error · UnsupportedOperationException

Cannot resolve schema for version: ${schemaVersion}

Error message

Cannot resolve schema for version: ${schemaVersion}

What it means

KeyMetadataEncoder's package-private constructor resolves the Avro write schema for the requested schema version via StandardKeyMetadata.supportedAvroSchemaVersions(). Requesting a version outside the supported set means the encoder cannot serialize key metadata in that format.

Source

Thrown at core/src/main/java/org/apache/iceberg/encryption/KeyMetadataEncoder.java:68

  }

  /**
   * Creates a new {@link MessageEncoder} that will deconstruct {@link StandardKeyMetadata}
   * instances described by the schema version.
   *
   * <p>If {@code shouldCopy} is true, then buffers returned by {@code encode} are copied and will
   * not be modified by future calls to {@code encode}.
   *
   * <p>If {@code shouldCopy} is false, then buffers returned by {@code encode} wrap a thread-local
   * buffer that can be reused by future calls to {@code encode}, but may not be. Callers should
   * only set {@code shouldCopy} to false if the buffer will be copied before the current thread's
   * next call to {@code encode}.
   */
  KeyMetadataEncoder(byte schemaVersion, boolean shouldCopy) {
    Schema writeSchema = StandardKeyMetadata.supportedAvroSchemaVersions().get(schemaVersion);

    if (writeSchema == null) {
      throw new UnsupportedOperationException(
          "Cannot resolve schema for version: " + schemaVersion);
    }

    this.writer = GenericAvroWriter.create(writeSchema);
    this.schemaVersion = schemaVersion;
    this.copyOutputBytes = shouldCopy;
  }

  @Override
  public ByteBuffer encode(StandardKeyMetadata datum) throws IOException {
    BufferOutputStream temp = TEMP.get();
    temp.reset();
    temp.write(schemaVersion);
    encode(datum, temp);

    if (copyOutputBytes) {
      return temp.toBufferWithCopy();
    } else {

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Use a schema version constant from StandardKeyMetadata's supported versions (e.g. the current version constant) instead of a hardcoded number
2. Upgrade Iceberg if you genuinely need a newer key metadata schema version
3. Use the default KeyMetadataEncoder factory methods rather than constructing with an explicit version

Example fix

// before
new KeyMetadataEncoder((byte) 99, false); // UnsupportedOperationException
// after
new KeyMetadataEncoder(StandardKeyMetadata.CURRENT_VERSION, false);

if (!StandardKeyMetadata.supportedAvroSchemaVersions().containsKey(schemaVersion)) {
  throw new IllegalArgumentException("Unsupported schema version: " + schemaVersion);
}

When it happens

Trigger: Constructing KeyMetadataEncoder with a byte schemaVersion that is not a key in supportedAvroSchemaVersions() — typically a hardcoded or future version number.

Common situations: Custom tooling that hardcodes a schema version constant from a newer Iceberg release; typos in version constants when building encryption metadata writers.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Cannot resolve schema for version: ${writeSchemaVersion}
• Failed to serialize envelope key metadata
• Unknown serialize version: ${version}
• Unrecognized version or corrupt state: ${version}
• Unrecognized version or corrupt state: ${version}

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