{"record":{"id":"927700de1c72c3e4","repo":"apache/iceberg","slug":"cannot-resolve-schema-for-fingerprint","errorCode":null,"errorMessage":"Cannot resolve schema for fingerprint: ","messagePattern":"Cannot resolve schema for fingerprint: ","errorType":"exception","errorClass":"MissingSchemaException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/iceberg/data/avro/IcebergDecoder.java","lineNumber":124,"sourceCode":"    RawDecoder<D> decoder = RawDecoder.create(readSchema, PlannedDataReader::create, writeSchema);\n    decoders.put(fp, decoder);\n  }\n\n  private RawDecoder<D> getDecoder(long fp) {\n    RawDecoder<D> decoder = decoders.get(fp);\n    if (decoder != null) {\n      return decoder;\n    }\n\n    if (resolver != null) {\n      Schema writeSchema = resolver.findByFingerprint(fp);\n      if (writeSchema != null) {\n        addSchema(writeSchema);\n        return decoders.get(fp);\n      }\n    }\n\n    throw new MissingSchemaException(\"Cannot resolve schema for fingerprint: \" + fp);\n  }\n\n  @Override\n  public D decode(InputStream stream, D reuse) throws IOException {\n    byte[] header = HEADER_BUFFER.get();\n    try {\n      if (!readFully(stream, header)) {\n        throw new BadHeaderException(\"Not enough header bytes\");\n      }\n    } catch (IOException e) {\n      throw new IOException(\"Failed to read header and fingerprint bytes\", e);\n    }\n\n    if (IcebergEncoder.V1_HEADER[0] != header[0] || IcebergEncoder.V1_HEADER[1] != header[1]) {\n      throw new BadHeaderException(\n          String.format(\n              Locale.ROOT, \"Unrecognized header bytes: 0x%02X 0x%02X\", header[0], header[1]));\n    }","sourceCodeStart":106,"sourceCodeEnd":142,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/data/avro/IcebergDecoder.java#L106-L142","documentation":"IcebergDecoder resolves Avro decoders by schema fingerprint that were previously registered via addSchema(). If decode encounters a fingerprint that was never registered and no writeSchema was supplied, it throws this MissingSchemaException. It means the stream references a write schema the decoder doesn't know about.","triggerScenarios":"Decoding a stream produced with a schema whose 8-byte fingerprint is absent from the decoder's registry and constructed without a writeSchema fallback (new IcebergDecoder(reader, null) then decode(stream, reuse)).","commonSituations":"Reading data written by a different process/version with an evolved schema; forgetting to call addSchema for the writer's schema; constructing the decoder without the write schema argument.","solutions":["Pass the writer's Avro Schema as writeSchema when constructing IcebergDecoder so unknown fingerprints resolve.","Call addSchema(writerSchema) for every schema that may have produced the streams.","Ensure both producer and consumer register the same schema version; align schema evolution between writer and reader."],"exampleFix":"// before\nIcebergDecoder<Record> decoder = new IcebergDecoder<>(reader, null);\ndecoder.decode(stream, null); // MissingSchemaException for unknown fingerprint\n// after\nIcebergDecoder<Record> decoder = new IcebergDecoder<>(reader, writeSchema);\ndecoder.decode(stream, null);","handlingStrategy":"fallback","validationCode":"// ensure every producer schema is registered before decoding\nfor (Schema s : knownWriteSchemas) { decoder.addSchema(s); }","typeGuard":"null","tryCatchPattern":"try { return decoder.decode(stream, reuse); } catch (MissingSchemaException e) { decoder.addSchema(resolveSchemaFromCatalog(e.getMessage())); return decoder.decode(stream, reuse); }","preventionTips":["Always construct IcebergDecoder with the writeSchema when known","Register all historical write schemas via addSchema","Share a single schema registry between producer and consumer"],"tags":["avro","decoder","schema","fingerprint"],"backgroundTag":"resource-not-found","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"}