apache/iceberg · error · ParquetDecodingException

could not read page in col %s as the dictionary was missing

Error message

could not read page in col %s as the dictionary was missing for encoding %s

What it means

Thrown in initDataReader when a page's data encoding uses a dictionary but no dictionary was supplied (dictionary == null). Dictionary-based encodings cannot decode values without the dictionary page, so the library fails fast.

Source

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

            triplesRead,
            triplesCount,
            currentRL,
            currentDL),
        exception);
  }

  @Override
  protected void initDataReader(Encoding dataEncoding, ByteBufferInputStream in, int valueCount) {
    ValuesReader previousReader = values;

    this.valueEncoding = dataEncoding;

    // TODO: May want to change this so that this class is not dictionary-aware.
    // For dictionary columns, this class could rely on wrappers to correctly handle dictionaries
    // This isn't currently possible because RLE must be read by getDictionaryBasedValuesReader
    if (dataEncoding.usesDictionary()) {
      if (dictionary == null) {
        throw new ParquetDecodingException(
            "could not read page in col "
                + desc
                + " as the dictionary was missing for encoding "
                + dataEncoding);
      }
      this.values =
          dataEncoding.getDictionaryBasedValuesReader(desc, ValuesType.VALUES, dictionary);
    } else {
      this.values = dataEncoding.getValuesReader(desc, ValuesType.VALUES);
    }

    //    if (dataEncoding.usesDictionary() && converter.hasDictionarySupport()) {
    //      bindToDictionary(dictionary);
    //    } else {
    //      bind(path.getType());
    //    }

    try {

View on GitHub (pinned to 86d9c8fc54)

Solutions

Validate/repair the Parquet file (dictionary page missing)
Rewrite the file with dictionary encoding disabled (parquet.enable.dictionary=false)
Upgrade writer/reader libraries to ensure dictionary pages are emitted/consumed correctly

Example fix

// before
// writer: parquet.enable.dictionary=true with corrupt dict page
// after
writer.parquet.enable.dictionary=false // or repair the source file

Defensive patterns

Strategy: validation

Validate before calling

// ensure dictionary page exists before data pages that use dictionary encoding
if (pageHeader.getType() != PageType.DICTIONARY_PAGE && pageHeader.getDataPageHeader().getEncoding().usesDictionary() && dictionary == null) throw new IllegalStateException("Missing dictionary page");

Try / catch

try {
  iterator.next();
} catch (ParquetDecodingException e) {
  if (e.getMessage().contains("dictionary was missing")) { /* repair/rewrite file */ }
  else throw e;
}

Prevention

Disable dictionary encoding if writer/reader combinations are unreliable
Verify complete file copies (dictionary page is at column-chunk start)
Test files from new writers with a full read before production

When it happens

Trigger: Reading a data page whose Encoding.usesDictionary() is true (PLAIN_DICTIONARY, RLE_DICTIONARY) while the preceding dictionary page is absent or not yet initialized.

Common situations: Corrupt/truncated files missing the dictionary page; readers skipping pages out of order; files produced by writers emitting dictionary encodings incorrectly.

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/b32fb1ad27fa1304. Report an issue: GitHub.