apache/iceberg · error · UnsupportedOperationException

Unsupported nested type:

Error message

Unsupported nested type:

What it means

ColumnVectorWithFilter wraps a delegate column vector and pre-builds filtered child vectors for nested types. Only arrays and structs (with up to two children in this branch) are supported; any other nested data type reaches the else branch and throws UnsupportedOperationException.

Source

Thrown at spark/v4.0/spark/src/main/java/org/apache/iceberg/spark/data/vectorized/ColumnVectorWithFilter.java:154

  @Override
  public ColumnVector getChild(int ordinal) {
    if (children == null) {
      synchronized (this) {
        if (children == null) {
          if (dataType() instanceof StructType) {
            StructType structType = (StructType) dataType();
            this.children = new ColumnVectorWithFilter[structType.length()];
            for (int index = 0; index < structType.length(); index++) {
              children[index] = new ColumnVectorWithFilter(delegate.getChild(index), rowIdMapping);
            }
          } else if (dataType() instanceof VariantType) {
            this.children =
                new ColumnVectorWithFilter[] {
                  new ColumnVectorWithFilter(delegate.getChild(0), rowIdMapping),
                  new ColumnVectorWithFilter(delegate.getChild(1), rowIdMapping)
                };
          } else {
            throw new UnsupportedOperationException("Unsupported nested type: " + dataType());
          }
        }
      }
    }

    return children[ordinal];
  }
}

View on GitHub (pinned to 86d9c8fc54)

Solutions

  1. Avoid vectorized reads for the offending nested type (set read.arrow-vectorized.enabled=false or table property read.split.vectorization.enabled=false)
  2. Restructure the schema so the unsupported nested type (e.g. map inside filtered read) is not selected in the batch read
  3. Upgrade Iceberg — nested-type coverage in ColumnVectorWithFilter expands over releases
  4. If confirmed missing support, file an Iceberg issue with the schema and read config

Example fix

// before
.read().select("id", "my_map") // map hits unsupported nested type
// after
.read().select("id") // or disable vectorization for this read
Defensive patterns

Strategy: validation

Validate before calling

if (dataType instanceof MapType) { disableVectorization(); } else { readWithVectors(); }

Try / catch

try { child = filteredVector.getChild(ordinal); } catch (UnsupportedOperationException e) { // fall back to non-vectorized read }
spark.conf.set("read.split.vectorization.enabled", "false");

Prevention

When it happens

Trigger: Calling getChild(ordinal) on a ColumnVectorWithFilter whose delegate's data type is a nested type other than the supported array/struct shapes — e.g. a map column selected through a row-id filtered vectorized read.

Common situations: Reading tables with map-typed columns when deletion/filter vectors require child wrapping; also appears after Spark or Iceberg version changes introduce new nested types the wrapper does not handle.

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