apache/iceberg · error · ParquetDecodingException

could not decode the dictionary for <desc>

Error message

could not decode the dictionary for <desc>

What it means

ParquetUtil.readDictionary fetches the dictionary page for a column and asks Parquet's encoding to build a Dictionary. If dictionary decoding throws IOException, it is wrapped in ParquetDecodingException with the column descriptor in the message. This indicates a corrupt or unreadable dictionary page for that column.

Source

Thrown at parquet/src/main/java/org/apache/iceberg/parquet/ParquetUtil.java:154

      // if PLAIN_DICTIONARY wasn't present, then either the column is not
      // dictionary-encoded, or the 2.0 encoding, RLE_DICTIONARY, was used.
      // for 2.0, this cannot determine whether a page fell back without
      // page encoding stats
      return true;
    }
  }

  public static boolean hasNoBloomFilterPages(ColumnChunkMetaData meta) {
    return meta.getBloomFilterOffset() <= 0;
  }

  public static Dictionary readDictionary(ColumnDescriptor desc, PageReader pageSource) {
    DictionaryPage dictionaryPage = pageSource.readDictionaryPage();
    if (dictionaryPage != null) {
      try {
        return dictionaryPage.getEncoding().initDictionary(desc, dictionaryPage);
      } catch (IOException e) {
        throw new ParquetDecodingException("could not decode the dictionary for " + desc, e);
      }
    }
    return null;
  }

  public static boolean isIntType(PrimitiveType primitiveType) {
    if (primitiveType.getOriginalType() != null) {
      switch (primitiveType.getOriginalType()) {
        case INT_8:
        case INT_16:
        case INT_32:
        case DATE:
          return true;
        default:
          return false;
      }
    }
    return primitiveType.getPrimitiveTypeName() == PrimitiveType.PrimitiveTypeName.INT32;

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Validate the Parquet file for corruption (parquet-tools / metadata dump) and rewrite from source data.
2. Confirm the file's writer version/encodings are supported by your Parquet library version; upgrade if needed.
3. Re-read from a valid table snapshot if the file was produced by a failed commit.
4. If the column can be read without dictionary, check whether disabling vectorized/dictionary-based reads in the engine helps isolate the issue.

Example fix

// before
Dictionary dict = ParquetUtil.readDictionary(desc, pageSource); // ParquetDecodingException
// after
try {
  Dictionary dict = ParquetUtil.readDictionary(desc, pageSource);
} catch (ParquetDecodingException e) {
  LOG.error("Corrupt dictionary for column {}", desc, e);
  throw e;
}

try {
  Dictionary dict = ParquetUtil.readDictionary(desc, pageSource);
} catch (ParquetDecodingException e) {
  LOG.error("Bad dictionary for {}", desc, e);
  throw e;
}

When it happens

Trigger: Reading a column that uses dictionary encoding where pageSource.readDictionaryPage() returns a page whose bytes cannot be decoded (corrupt page, wrong encoding flag, truncated dictionary data).

Common situations: Reading files damaged by interrupted writes or bad storage; files written by writers with encoding bugs; mismatched/incorrect column descriptors passed to readDictionary.

Understand the failure class

Background: Checksum mismatch errors: "checksum verification failed", "digest mismatch", "expected vs actual checksum" — what they mean and how to fix them — this error's family across 41 libraries.

Related errors

• could not read page %s in col %s
• Failed to read a byte
• Non-supported bytesWidth: " + bytesWidth
• not a valid mode " + this.mode
• No more values to read. Total values read: " + valuesRead +

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