apache/iceberg · error · ParquetDecodingException

Can not decode bitwidth in block header

Error message

Can not decode bitwidth in block header

What it means

readBitWidthsForMiniBlocks reads the bit width byte for each mini block in a DELTA_BINARY_PACKED block header using BytesUtils.readIntLittleEndianOnOneByte. An IOException here (stream exhausted before all mini-block bit widths are read) is wrapped in ParquetDecodingException. It indicates the block header is truncated or the stream is misaligned.

Source

Thrown at arrow/src/main/java/org/apache/iceberg/arrow/vectorized/parquet/VectorizedDeltaEncodedValuesReader.java:248

      ByteBuffer buffer = inputStream.slice(packer.getBitWidth());
      if (buffer.hasArray()) {
        packer.unpack8Values(
            buffer.array(), buffer.arrayOffset() + buffer.position(), unpackedValuesBuffer, j);
      } else {
        packer.unpack8Values(buffer, buffer.position(), unpackedValuesBuffer, j);
      }
    }
    remainingInMiniBlock = miniBlockSizeInValues;
    currentMiniBlock++;
  }

  // From org.apache.parquet.column.values.delta.DeltaBinaryPackingValuesReader
  private void readBitWidthsForMiniBlocks() {
    for (int i = 0; i < miniBlocksPerBlock; i++) {
      try {
        bitWidths[i] = BytesUtils.readIntLittleEndianOnOneByte(inputStream);
      } catch (IOException e) {
        throw new ParquetDecodingException("Can not decode bitwidth in block header", e);
      }
    }
  }

  /** A functional interface to write long values to into a FieldVector */
  @FunctionalInterface
  interface IntegerOutputWriter {

    /**
     * A functional interface that can be used to write a long value to a specified row in a
     * FieldVector
     *
     * @param vec a FieldVector to write the value into
     * @param index The offset to write to
     * @param val value to write
     */
    void write(FieldVector vec, long index, long val);
  }

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Retry the read to exclude transient IO errors, then validate the file.
2. Rewrite the corrupt/truncated data files from source data.
3. Upgrade or fix the writer producing the delta-encoded files.
4. Fall back to non-vectorized reads while investigating.

try {
  // vectorized read
} catch (ParquetDecodingException e) {
  if (e.getMessage().contains("Can not decode bitwidth in block header")) {
    // treat page/file as truncated: rewrite or fallback reader
  } else throw e;
}

When it happens

Trigger: readBlockHeader -> readBitWidthsForMiniBlocks when the input stream ends (or errors) before miniBlocksPerBlock bit-width bytes have been consumed.

Common situations: Truncated or corrupt delta-encoded data pages, partial file uploads, or files written by a non-conforming encoder.

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

• not a valid mode " + this.mode
• No more values to read. Total values read: " + valuesRead +
• Can not read min delta in current block
• Read failure possibly due to PARQUET-246: try setting parque
• Can't read value in column %s at value %d out of %d in curre

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