apache/iceberg · error · ParquetDecodingException

Read failure possibly due to PARQUET-246: try setting parque

Error message

Read failure possibly due to PARQUET-246: try setting parquet.split.files to false

What it means

handleRuntimeException detects that an ArrayIndexOutOfBoundsException during value decoding is likely the Parquet bug PARQUET-246: DeltaByteArray-encoded pages require sequential reads, which fail when file splits were created without reading footers. It rethrows as ParquetDecodingException with a workaround hint.

Source

Thrown at parquet/src/main/java/org/apache/iceberg/parquet/PageIterator.java:211

  private void advance() {
    if (triplesRead < triplesCount) {
      this.currentDL = definitionLevels.nextInt();
      this.currentRL = repetitionLevels.nextInt();
      this.triplesRead += 1;
      this.hasNext = true;
    } else {
      this.currentDL = -1;
      this.currentRL = -1;
      this.hasNext = false;
    }
  }

  RuntimeException handleRuntimeException(RuntimeException exception) {
    if (CorruptDeltaByteArrays.requiresSequentialReads(writerVersion, valueEncoding)
        && exception instanceof ArrayIndexOutOfBoundsException) {
      // this is probably PARQUET-246, which may happen if reading data with
      // MR because this can't be detected without reading all footers
      throw new ParquetDecodingException(
          "Read failure possibly due to " + "PARQUET-246: try setting parquet.split.files to false",
          new ParquetDecodingException(
              String.format(
                  Locale.ROOT,
                  "Can't read value in column %s at value %d out of %d in current page. "
                      + "repetition level: %d, definition level: %d",
                  desc,
                  triplesRead,
                  triplesCount,
                  currentRL,
                  currentDL),
              exception));
    }
    throw new ParquetDecodingException(
        String.format(
            Locale.ROOT,
            "Can't read value in column %s at value %d out of %d in current page. "
                + "repetition level: %d, definition level: %d",

View on GitHub (pinned to 86d9c8fc54)

Solutions

Set parquet.split.files to false (spark.sql.files.split=false style config) so files are read sequentially
Rewrite the file with a newer Parquet writer version
Upgrade Iceberg/Parquet libraries to pick up PARQUET-246 fixes

Example fix

// before
spark.conf.set("spark.sql.files.maxPartitionBytes", "1MB") // aggressive splits
// after
spark.conf.set("parquet.split.files", "false")

Defensive patterns

Strategy: retry

Validate before calling

Encoding enc = pageHeader.getDataPageHeader().getEncoding();
if (enc == Encoding.DELTA_BYTE_ARRAY) { /* ensure sequential read / disable splits before reading */ }

Try / catch

try {
  iterator.nextBinary();
} catch (ParquetDecodingException e) {
  if (e.getMessage().contains("PARQUET-246")) { /* re-read with splitting disabled */ }
  else throw e;
}

Prevention

Disable file splitting for files written by old MR Parquet writers
Rewrite old files with a current Parquet writer version
Record writer versions in metadata and route old files to sequential readers

When it happens

Trigger: Calling nextBoolean/nextInteger/nextLong/nextFloat/nextDouble/nextBinary on a page with DeltaByteArray encoding while an ArrayIndexOutOfBoundsException occurs and the writer version requires sequential reads.

Common situations: Reading files written by older Parquet/MR writers in a split-parallel reader (e.g. Spark) hitting the PARQUET-246 defect.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

AI-assisted analysis of apache/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/24344df7b5dadb23. Report an issue: GitHub.