{"record":{"id":"f75b934108be56af","repo":"apache/iceberg","slug":"unrecognized-header-bytes-0x-02x-0x-02x-f75b93","errorCode":null,"errorMessage":"Unrecognized header bytes: 0x%02X 0x%02X","messagePattern":"Unrecognized header bytes: 0x%02X 0x%02X","errorType":"exception","errorClass":"BadHeaderException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/iceberg/data/avro/IcebergDecoder.java","lineNumber":140,"sourceCode":"    }\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    }\n\n    RawDecoder<D> decoder = getDecoder(FP_BUFFER.get().getLong(2));\n\n    try {\n      return decoder.decode(stream, reuse);\n    } catch (UncheckedIOException e) {\n      throw new AvroRuntimeException(e);\n    }\n  }\n\n  /**\n   * Reads a buffer from a stream, making multiple read calls if necessary.\n   *\n   * @param stream an InputStream to read from\n   * @param bytes a buffer\n   * @return true if the buffer is complete, false otherwise (stream ended)","sourceCodeStart":122,"sourceCodeEnd":158,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/data/avro/IcebergDecoder.java#L122-L158","documentation":"After reading the header, decode validates the first two magic bytes against IcebergEncoder.V1_HEADER. If they don't match, it throws BadHeaderException with the offending bytes formatted as hex. The data isn't in the Iceberg binary-encoded format this decoder expects.","triggerScenarios":"Decoding a stream not produced by IcebergEncoder: raw Avro files, other binary formats, a stream offset by a few bytes, or a different encoding version's header.","commonSituations":"Pointing the decoder at an Avro object-container file instead of Iceberg raw-encoded data; starting the read mid-stream (skipping bytes); decoding output of an incompatible writer version.","solutions":["Confirm the data was written by IcebergEncoder (V1 header) rather than plain Avro DataFileWriter.","Ensure the stream starts exactly at the beginning of the encoded record — do not skip/offset bytes.","Check writer/decoder version compatibility (header version mismatch).","Log the hex bytes from the message to identify the actual format."],"exampleFix":"// before\nInputStream in = new FileInputStream(avroContainerFile);\ndecoder.decode(in, null); // Unrecognized header bytes: 0x4F 0x62\n// after\nInputStream in = new FileInputStream(rawEncodedFile); // produced by IcebergEncoder\ndecoder.decode(in, null);","handlingStrategy":"validation","validationCode":"byte[] magic = new byte[2];\nif (new DataInputStream(in).read(magic) != 2 || magic[0] != IcebergEncoder.V1_HEADER[0] || magic[1] != IcebergEncoder.V1_HEADER[1]) {\n  throw new IllegalArgumentException(\"Not Iceberg raw-encoded data\");\n}","typeGuard":"null","tryCatchPattern":"try { return decoder.decode(stream, reuse); } catch (BadHeaderException e) { throw new IllegalStateException(\"Stream is not Iceberg-encoded: \" + e.getMessage(), e); }","preventionTips":["Only decode streams produced by IcebergEncoder","Never start reading mid-stream","Check header bytes manually when debugging format issues"],"tags":["avro","decoder","format","header"],"backgroundTag":"unexpected-response-shape","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"}