{"record":{"id":"c4893eaf4f5da4dc","repo":"apache/iceberg","slug":"cannot-resolve-schema-for-version-schemaversion","errorCode":null,"errorMessage":"Cannot resolve schema for version: ${schemaVersion}","messagePattern":"Cannot resolve schema for version: (.+?)","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/iceberg/encryption/KeyMetadataEncoder.java","lineNumber":68,"sourceCode":"  }\n\n  /**\n   * Creates a new {@link MessageEncoder} that will deconstruct {@link StandardKeyMetadata}\n   * instances described by the schema version.\n   *\n   * <p>If {@code shouldCopy} is true, then buffers returned by {@code encode} are copied and will\n   * not be modified by future calls to {@code encode}.\n   *\n   * <p>If {@code shouldCopy} is false, then buffers returned by {@code encode} wrap a thread-local\n   * buffer that can be reused by future calls to {@code encode}, but may not be. Callers should\n   * only set {@code shouldCopy} to false if the buffer will be copied before the current thread's\n   * next call to {@code encode}.\n   */\n  KeyMetadataEncoder(byte schemaVersion, boolean shouldCopy) {\n    Schema writeSchema = StandardKeyMetadata.supportedAvroSchemaVersions().get(schemaVersion);\n\n    if (writeSchema == null) {\n      throw new UnsupportedOperationException(\n          \"Cannot resolve schema for version: \" + schemaVersion);\n    }\n\n    this.writer = GenericAvroWriter.create(writeSchema);\n    this.schemaVersion = schemaVersion;\n    this.copyOutputBytes = shouldCopy;\n  }\n\n  @Override\n  public ByteBuffer encode(StandardKeyMetadata datum) throws IOException {\n    BufferOutputStream temp = TEMP.get();\n    temp.reset();\n    temp.write(schemaVersion);\n    encode(datum, temp);\n\n    if (copyOutputBytes) {\n      return temp.toBufferWithCopy();\n    } else {","sourceCodeStart":50,"sourceCodeEnd":86,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/encryption/KeyMetadataEncoder.java#L50-L86","documentation":"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.","triggerScenarios":"Constructing KeyMetadataEncoder with a byte schemaVersion that is not a key in supportedAvroSchemaVersions() — typically a hardcoded or future version number.","commonSituations":"Custom tooling that hardcodes a schema version constant from a newer Iceberg release; typos in version constants when building encryption metadata writers.","solutions":["Use a schema version constant from StandardKeyMetadata's supported versions (e.g. the current version constant) instead of a hardcoded number","Upgrade Iceberg if you genuinely need a newer key metadata schema version","Use the default KeyMetadataEncoder factory methods rather than constructing with an explicit version"],"exampleFix":"// before\nnew KeyMetadataEncoder((byte) 99, false); // UnsupportedOperationException\n// after\nnew KeyMetadataEncoder(StandardKeyMetadata.CURRENT_VERSION, false);","handlingStrategy":"validation","validationCode":"if (!StandardKeyMetadata.supportedAvroSchemaVersions().containsKey(schemaVersion)) {\n  throw new IllegalArgumentException(\"Unsupported schema version: \" + schemaVersion);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use StandardKeyMetadata's version constants instead of hardcoded bytes","Prefer default encoder factory methods over explicit version construction","Add a unit test covering encoder construction with the shipped version constant"],"tags":["encryption","versioning","serialization"],"backgroundTag":"invalid-argument-value","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"}