What causes "Cannot decode dictionary of type: " in apache/iceberg?

Rewrite the data so columns use standard supported primitive types.

apache/iceberg · error · IllegalArgumentException

Cannot decode dictionary of type

Error message

Cannot decode dictionary of type: <type>

What it means

Thrown while decoding dictionary entries when the column's Parquet primitive type has no decode branch (anything other than the INT32/INT64/FLOAT/DOUBLE/BINARY/FIXED_LEN_BYTE_ARRAY/INT96 paths implemented). The dictionary reader returns values via typed decode methods and this default branch catches unsupported primitives.

Solutions

Rewrite the data so columns use standard supported primitive types.
Upgrade Iceberg to a version supporting the type.
Exclude such columns from dictionary filtering (fall back to record-level filtering).

Example fix

// before
Dictionary built for a column with an unsupported primitive (e.g. FLOAT16)
// after
rewrite the column as FIXED_LEN_BYTE_ARRAY(2) or BINARY and adjust the Iceberg schema accordingly

Defensive patterns

Strategy: fallback

Validate before calling

PrimitiveType.PrimitiveTypeName name = col.getPrimitiveType().getPrimitiveTypeName();
boolean decodable = name == PrimitiveType.PrimitiveTypeName.INT32
    || name == PrimitiveType.PrimitiveTypeName.INT64
    || name == PrimitiveType.PrimitiveTypeName.FLOAT
    || name == PrimitiveType.PrimitiveTypeName.DOUBLE
    || name == PrimitiveType.PrimitiveTypeName.BINARY
    || name == PrimitiveType.PrimitiveTypeName.FIXED_LEN_BYTE_ARRAY
    || name == PrimitiveType.PrimitiveTypeName.INT96;
if (!decodable) {
  // skip dictionary filtering for this column
}

Try / catch

try {
  boolean mayMatch = dictFilter.shouldRead(...);
} catch (IllegalArgumentException e) {
  LOG.warn("Undecodable dictionary type, falling back", e);
  mayMatch = true;
}

Prevention

Use only standard Parquet primitive types in schemas.
Upgrade Iceberg when reading files with newer types.
Restrict dictionary pushdown to well-known column types.

When it happens

Trigger: A Parquet column with an exotic/unsupported primitive type reaching the dictionary filter's decode loop, e.g. from malformed schema metadata or a type added to Parquet that the filter doesn't handle.

Common situations: Files with nonstandard schema; future/bleeding-edge Parquet types read by older Iceberg; hand-built Parquet schemas in tests.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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

Appendix: source

Thrown at parquet/src/main/java/org/apache/iceberg/parquet/ParquetDictionaryRowGroupFilter.java:467

            dictSet.add((T) conversion.apply(dict.decodeToBinary(i)));
            break;
          case INT32:
            dictSet.add((T) conversion.apply(dict.decodeToInt(i)));
            break;
          case INT64:
            dictSet.add((T) conversion.apply(dict.decodeToLong(i)));
            break;
          case FLOAT:
            dictSet.add((T) conversion.apply(dict.decodeToFloat(i)));
            break;
          case DOUBLE:
            dictSet.add((T) conversion.apply(dict.decodeToDouble(i)));
            break;
          case INT96:
            dictSet.add((T) conversion.apply(dict.decodeToBinary(i)));
            break;
          default:
            throw new IllegalArgumentException(
                "Cannot decode dictionary of type: "
                    + col.getPrimitiveType().getPrimitiveTypeName());
        }
      }

      dictCache.put(id, dictSet);

      return dictSet;
    }

    @Override
    public <T> Boolean handleNonReference(Bound<T> term) {
      return ROWS_MIGHT_MATCH;
    }
  }

  private static boolean mayContainNull(ColumnChunkMetaData meta) {
    return meta.getStatistics() == null || meta.getStatistics().getNumNulls() != 0;

View on GitHub (pinned to 86d9c8fc54)