{"record":{"id":"8919950900d0ccc2","repo":"apache/iceberg","slug":"failed-to-read-header-and-fingerprint-bytes","errorCode":null,"errorMessage":"Failed to read header and fingerprint bytes","messagePattern":"Failed to read header and fingerprint bytes","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/iceberg/data/avro/IcebergDecoder.java","lineNumber":135,"sourceCode":"      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    }\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  /**","sourceCodeStart":117,"sourceCodeEnd":153,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/data/avro/IcebergDecoder.java#L117-L153","documentation":"When reading the header throws an IOException (I/O failure rather than a short stream), IcebergDecoder.decode wraps it in a new IOException with the message \"Failed to read header and fingerprint bytes\" and the original exception as cause. It indicates an underlying I/O problem while reading the stream's header.","triggerScenarios":"decode(stream, reuse) where stream.read() throws mid-header: broken file handle, network stream reset, closed InputStream, or disk read error.","commonSituations":"Reading from a remote/encrypted FS where the connection drops; stream closed by another component; permissions/IO errors on read.","solutions":["Inspect the cause IOException for the root I/O failure.","Verify the InputStream is open and reachable at decode time.","Retry the read if the source is transiently unavailable (network FS, object store).","Ensure no other thread closes the shared stream concurrently."],"exampleFix":"// before\ndecoder.decode(stream, null); // IOException: Failed to read header...\n// after\ntry {\n  decoder.decode(stream, null);\n} catch (IOException e) {\n  if (e.getCause() != null) log.warn(\"Root cause\", e.getCause());\n  throw e;\n}","handlingStrategy":"retry","validationCode":"null","typeGuard":"null","tryCatchPattern":"try { return decoder.decode(stream, reuse); } catch (IOException e) { if (isTransient(e.getCause())) { return retryDecode(stream, reuse); } throw e; }","preventionTips":["Keep the InputStream open until decode completes","Use durable local files instead of flaky network streams when possible","Inspect the cause chain for the real I/O failure"],"tags":["avro","io","stream","decoder"],"backgroundTag":"file-read-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"}