apache/iceberg · error · UnsupportedOperationException

toByteBuffer is not supported

Error message

toByteBuffer is not supported

What it means

Literal.toByteBuffer() is a default method on the Literal interface that throws UnsupportedOperationException because not every literal can be serialized to Iceberg's single-value binary format. Sentinel literals such as AboveMax, BelowMin, and other special literals have no concrete value to serialize. It is thrown when code asks a non-serializable literal for its binary representation.

Source

Thrown at api/src/main/java/org/apache/iceberg/expressions/Literal.java:113

   * @return A literal of the given type or null if conversion was not valid
   */
  <X> Literal<X> to(Type type);

  /**
   * Return a {@link Comparator} for values.
   *
   * @return a comparator for T objects
   */
  Comparator<T> comparator();

  /**
   * Serializes the value wrapped by this literal to binary using the single-value serialization
   * format described in the Iceberg table specification.
   *
   * @return a ByteBuffer that contains the serialized literal value.
   */
  default ByteBuffer toByteBuffer() {
    throw new UnsupportedOperationException("toByteBuffer is not supported");
  }
}

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Check the literal type before serializing (skip AboveMax/BelowMin and other sentinel literals)
2. Use Literals.value() only on concrete value literals; treat sentinels specially (e.g. as +/- infinity bounds)
3. Catch UnsupportedOperationException and handle sentinel literals explicitly in the conversion code

Example fix

// before
ByteBuffer buf = lit.toByteBuffer(); // throws for AboveMax
// after
ByteBuffer buf = (lit instanceof Literals.AboveMax || lit instanceof Literals.BelowMin)
    ? null : lit.toByteBuffer();

boolean serializable = !(lit instanceof Literals.AboveMax)
    && !(lit instanceof Literals.BelowMin);

static boolean hasByteBuffer(Literal<?> lit) {
  return !(lit instanceof Literals.AboveMax) && !(lit instanceof Literals.BelowMin);
}

ByteBuffer buf;
try {
  buf = lit.toByteBuffer();
} catch (UnsupportedOperationException e) {
  if (e.getMessage().contains("toByteBuffer is not supported")) {
    buf = null; // sentinel literal, skip bound extraction
  } else {
    throw e;
  }
}

When it happens

Trigger: Calling literal.toByteBuffer() on a sentinel literal (AboveMax/BelowMin from conversions, count-star-like special literals) or any Literal subclass that intentionally does not implement serialization; e.g. converting an expression's literals to lower/upper bounds or writing them to manifest/parquet statistics.

Common situations: Pushing filter literals into file statistics or prefix computations (truncate/prefixAsBytes) when the expression contains aboveMax/belowMin produced by Literal.to(Type) conversions that overflow the target type.

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

• AboveMax has no value
• Cannot change the type of AboveMax
• Cannot create expression literal from %s: %s
• Failed to encode value as UTF-8: %s
• Cannot serialize type: + typeId

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