{"record":{"id":"f025746d699e3c4c","repo":"apache/iceberg","slug":"cannot-resolve-schema-for-version-writeschemave","errorCode":null,"errorMessage":"Cannot resolve schema for version: ${writeSchemaVersion}","messagePattern":"Cannot resolve schema for version: (.+?)","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/iceberg/encryption/KeyMetadataDecoder.java","lineNumber":62,"sourceCode":"\n  @Override\n  public StandardKeyMetadata decode(InputStream stream, StandardKeyMetadata reuse) {\n    byte writeSchemaVersion;\n\n    try {\n      writeSchemaVersion = (byte) stream.read();\n    } catch (IOException e) {\n      throw new UncheckedIOException(\"Failed to read the version byte\", e);\n    }\n\n    if (writeSchemaVersion < 0) {\n      throw new RuntimeException(\"Version byte - end of stream reached\");\n    }\n\n    Schema writeSchema = StandardKeyMetadata.supportedAvroSchemaVersions().get(writeSchemaVersion);\n\n    if (writeSchema == null) {\n      throw new UnsupportedOperationException(\n          \"Cannot resolve schema for version: \" + writeSchemaVersion);\n    }\n\n    RawDecoder<StandardKeyMetadata> decoder = decoders.get(writeSchemaVersion);\n\n    if (decoder == null) {\n      decoder = RawDecoder.create(readSchema, GenericAvroReader::create, writeSchema);\n\n      decoders.put(writeSchemaVersion, decoder);\n    }\n\n    return decoder.decode(stream, reuse);\n  }\n}\n","sourceCodeStart":44,"sourceCodeEnd":77,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/encryption/KeyMetadataDecoder.java#L44-L77","documentation":"decode reads a one-byte schema version from the key metadata blob and looks it up in StandardKeyMetadata.supportedAvroSchemaVersions(). If the byte does not map to a known write schema, the blob was produced by an incompatible (newer or corrupt) writer and cannot be decoded by this Iceberg version.","triggerScenarios":"Decoding key metadata whose version byte is not among the supported Avro schema versions — e.g. metadata written by a newer Iceberg release, or corrupted/offset bytes.","commonSituations":"Opening encrypted tables written by a newer Iceberg version with an older client; byte corruption in stored metadata; passing non-key-metadata bytes to the decoder.","solutions":["Upgrade to an Iceberg version that supports the key metadata schema version in the blob","Verify the metadata bytes are intact and actually StandardKeyMetadata output","Rewrite the table's encryption metadata with a compatible Iceberg version"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// preflight: peek the first byte and check support\nint version = buffer.duplicate().get();\nif (!StandardKeyMetadata.supportedAvroSchemaVersions().containsKey((byte) version)) {\n  throw new UnsupportedOperationException(\"Unsupported key metadata version: \" + version);\n}","typeGuard":null,"tryCatchPattern":"try { return StandardKeyMetadata.parse(buffer); }\ncatch (RuntimeException e) {\n  if (e.getMessage().startsWith(\"Cannot resolve schema for version\")) { /* upgrade path */ }\n  throw e;\n}","preventionTips":["Keep Iceberg versions aligned between writers and readers of encrypted tables","Peek the version byte before decoding to fail fast with a clear message","Do not hand-modify key metadata bytes"],"tags":["encryption","versioning","deserialization","compatibility"],"backgroundTag":"schema-validation-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"}