{"record":{"id":"3b61bcfbbd88d196","repo":"apache/iceberg","slug":"failed-to-read-a-byte","errorCode":null,"errorMessage":"Failed to read a byte","messagePattern":"Failed to read a byte","errorType":"exception","errorClass":"ParquetDecodingException","httpStatus":null,"severity":"error","filePath":"parquet/src/main/java/org/apache/iceberg/parquet/ValuesAsBytesReader.java","lineNumber":109,"sourceCode":"\n  /** Returns 1 if true, 0 otherwise. */\n  public final int readBooleanAsInt() {\n    if (bitOffset == 0) {\n      currentByte = getByte();\n    }\n    int value = (currentByte & (1 << bitOffset)) >> bitOffset;\n    bitOffset += 1;\n    if (bitOffset == 8) {\n      bitOffset = 0;\n    }\n    return value;\n  }\n\n  private byte getByte() {\n    try {\n      return (byte) valuesInputStream.read();\n    } catch (IOException e) {\n      throw new ParquetDecodingException(\"Failed to read a byte\", e);\n    }\n  }\n}\n","sourceCodeStart":91,"sourceCodeEnd":113,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/parquet/src/main/java/org/apache/iceberg/parquet/ValuesAsBytesReader.java#L91-L113","documentation":"Thrown by ValuesAsBytesReader.getByte() when the underlying values InputStream throws an IOException while reading the next byte during Parquet value decoding. The library wraps the checked IOException in a ParquetDecodingException because decoding happens inside reader loops that do not declare checked exceptions. It almost always indicates truncated or corrupt page data rather than a data-type problem.","triggerScenarios":"Reading a boolean/int8 column value via readBoolean or readBooleanAsInt when the page's valuesInputStream is exhausted early or the underlying file/byte buffer is unreadable mid-read.","commonSituations":"Truncated Parquet files from interrupted writes or failed downloads; corrupt page payloads; a FileIO returning a stream over a truncated or partially-updated object (e.g. reading a file while it is being overwritten); filesystem/network I/O errors during reads.","solutions":["Verify the Parquet file is complete and not truncated (check file size vs manifest/expected length); re-copy or re-download the file.","Check for concurrent overwrites of the data file; ensure readers only access immutable, committed files.","Inspect the wrapped IOException (getCause) for the underlying filesystem/network error and fix that (permissions, connection, disk).","Re-run the read; transient network/IO errors may succeed on retry after validating the file integrity."],"exampleFix":"// before: reading a file while a writer replaces it\nTable table = catalog.loadTable(\"db.t\");\nCloseableIterable<Record> rows = SparkUtil.openAllDataFiles(table); // may include files being overwritten\n\n// after: read only committed snapshots and validate file presence\nTable table = catalog.loadTable(\"db.t\");\nsnapshot(table.currentSnapshot().snapshotId()) // pin snapshot so files are immutable\n    .dataFiles().forEach(f -> Preconditions.check(io.newInputFile(f.location()).exists(), \"missing file \" + f.location()));","handlingStrategy":"try-catch","validationCode":"InputFile f = io.newInputFile(location);\nlong actual = f.getLength();\nPreconditions.check(actual >= expectedMinSize, \"Truncated file %s: %s < %s\", location, actual, expectedMinSize);","typeGuard":null,"tryCatchPattern":"try {\n  readColumn(...);\n} catch (ParquetDecodingException e) {\n  if (e.getCause() instanceof IOException) {\n    verifyFileIntegrity(location); // check length/checksum, re-fetch\n    retryRead();\n  } else throw e;\n}","preventionTips":["Only read immutable, committed data files from a pinned snapshot","Verify file sizes/checksums after download or copy before reading","Watch for concurrent overwrites of objects in object stores","Inspect getCause() to distinguish corruption from transient IO errors"],"tags":["parquet","io","decoding","corrupt-file"],"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"}