apache/iceberg · error · UnsupportedOperationException

Creating %s from a Dictionary is not supported

Error message

Creating %s from a Dictionary is not supported

What it means

The string factory interface's default ofRow(IntVector, Dictionary, int) throws UnsupportedOperationException because dictionary-encoded values cannot be converted to the generic UTF8 type without an engine-specific implementation. Only concrete factories that implement dictionary decoding support this path.

Source

Thrown at arrow/src/main/java/org/apache/iceberg/arrow/vectorized/GenericArrowVectorAccessorFactory.java:827

   */
  protected interface StringFactory<Utf8StringT> {
    /** Class of concrete UTF8 String type. */
    Class<Utf8StringT> getGenericClass();

    /** Create a UTF8 String from the row value in the arrow vector. */
    Utf8StringT ofRow(VarCharVector vector, int rowId);

    /** Create a UTF8 String from the row value in the FixedSizeBinaryVector vector. */
    default Utf8StringT ofRow(FixedSizeBinaryVector vector, int rowId) {
      throw new UnsupportedOperationException(
          String.format(
              "Creating %s from a FixedSizeBinaryVector is not supported",
              getGenericClass().getSimpleName()));
    }

    /** Create a UTF8 String from the row value in the Dictionary. */
    default Utf8StringT ofRow(IntVector offsetVector, Dictionary dictionary, int rowId) {
      throw new UnsupportedOperationException(
          String.format(
              "Creating %s from a Dictionary is not supported", getGenericClass().getSimpleName()));
    }

    /** Create a UTF8 String from the byte array. */
    Utf8StringT ofBytes(byte[] bytes);

    /** Create a UTF8 String from the byte buffer. */
    Utf8StringT ofByteBuffer(ByteBuffer byteBuffer);
  }

  /**
   * Create an array value of type {@code ArrayT} from arrow vector value.
   *
   * @param <ArrayT> A concrete type that can represent an array value in a list vector, e.g.
   *     Spark's ColumnarArray.
   * @param <ChildVectorT> A concrete type that can represent a child vector in a struct, e.g.
   *     Spark's ArrowColumnVector.

View on GitHub (pinned to 86d9c8fc54)

Solutions

  1. Upgrade Iceberg to a version where the engine's StringFactory implements dictionary-based ofRow
  2. Disable vectorized reads for the affected scans
  3. Rewrite/compact the Parquet files with dictionary encoding disabled (writer option) if unavoidable

Example fix

// before
// dictionary-encoded strings + default factory -> throws
// after
table.updateProperties().set(TableProperties.PARQUET_VECTORIZATION_ENABLED, "false");
Defensive patterns

Strategy: fallback

Validate before calling

ParquetMetadata meta = ParquetFileReader.readFooter(...);
if (meta.getFileMetaData().getEncodingStats().hasDictionaryEncoding()
    && !factorySupportsDictionary()) {
  // use generic reader
}

Try / catch

try {
  return vectorizedReaderFactory.create();
} catch (UnsupportedOperationException e) {
  return nonVectorizedReader();
}

Prevention

When it happens

Trigger: A dictionary-encoded VarChar column read via vectorized path where the reader takes the dictionary branch (offsets vector + Dictionary) and the configured StringFactory did not override ofRow(IntVector, Dictionary, int).

Common situations: Parquet files written with dictionary encoding for string columns (very common) read by an engine integration lacking dictionary string support; older Iceberg versions before the engine factory implemented dictionary decoding.

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