apache/iceberg · error · UnsupportedOperationException

Creating %s from a FixedSizeBinaryVector is not supported

Error message

Creating %s from a FixedSizeBinaryVector is not supported

What it means

The StringFactory/Utf8 factory interface provides a default ofRow(FixedSizeBinaryVector, int) that throws UnsupportedOperationException because converting a fixed-size binary buffer to the generic UTF8 string type is not implemented by default. Concrete factory subclasses (e.g. Spark's) may override it; the default contract forbids it.

Source

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

    /** Create a decimal from the given {@link BigDecimal} value, precision and scale. */
    DecimalT ofBigDecimal(BigDecimal value, int precision, int scale);
  }

  /**
   * Create a UTF8 String value of type {@code Utf8StringT} from arrow vector value.
   *
   * @param <Utf8StringT> A concrete type that can represent a UTF8 string.
   */
  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);
  }

View on GitHub (pinned to 86d9c8fc54)

Solutions

Disable vectorized reads (parquet vectorization off) for tables containing fixed-size binary string data
Upgrade to an Iceberg version where the engine's StringFactory implements ofRow(FixedSizeBinaryVector, int)
Catch UnsupportedOperationException and fall back to the generic Parquet reader for such files

Example fix

// before
// default factory used for FixedSizeBinary string column -> throws
// after
collection.config().set(TableProperties.PARQUET_VECTORIZATION_ENABLED, "false");

Defensive patterns

Strategy: fallback

Validate before calling

if (columnPhysicalType.equals("FIXED_LEN_BYTE_ARRAY") && expectsString) {
  // disable vectorization or ensure factory overrides ofRow(FixedSizeBinaryVector)
}

Type guard

boolean stringFactorySupportsFixedSize(StringFactory<?> f) {
  try { f.getClass().getMethod("ofRow", FixedSizeBinaryVector.class, int.class); return true; }
  catch (NoSuchMethodException e) { return false; }
}

Try / catch

try {
  return vectorizedRead();
} catch (UnsupportedOperationException e) {
  return genericRead();
}

Prevention

Avoid fixed_len_byte_array string columns when possible
Use an engine integration whose StringFactory overrides fixed-size ofRow
Fall back to generic reads for such files

When it happens

Trigger: A FixedSizeBinaryVector-backed column (e.g. decimal or fixed_len_byte_array stored as FixedSizeBinary) reaches a string accessor path whose factory did not override ofRow(FixedSizeBinaryVector, int); getVectorAccessor routes fixed-size vectors to this default when the factory lacks the override.

Common situations: Reading fixed_len_byte_array string/binary columns with vectorized reads in an engine whose string factory was not extended; mixing engine versions where the factory override is missing.

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