apache/iceberg · error · java.lang.UnsupportedOperationException

Unsupported nested type: ${dataType()}

Error message

Unsupported nested type: ${dataType()}

What it means

ColumnVectorWithFilter wraps a column vector to apply a row-id selection (filtered batch reads). Its getChild lazily wraps child vectors for nested columns; it supports only array/map (via delegate), and struct children by rebuilding child ColumnVectorWithFilter instances. If the wrapped vector's data type is neither of those, it throws UnsupportedOperationException because filtered access to that nested type is not implemented.

Source

Thrown at spark/v3.5/spark/src/main/java/org/apache/iceberg/spark/data/vectorized/ColumnVectorWithFilter.java:147

  @Override
  public byte[] getBinary(int rowId) {
    return delegate.getBinary(rowIdMapping[rowId]);
  }

  @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 {
            throw new UnsupportedOperationException("Unsupported nested type: " + dataType());
          }
        }
      }
    }

    return children[ordinal];
  }
}

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Upgrade the Iceberg Spark runtime to match your Spark version so nested filtered reads are supported
2. Rewrite the query to avoid projecting the unsupported nested column (or read it without the filter)
3. Compact/rewrite data files to remove delete files so the plain (non-filtered) vector path is used
4. Disable vectorization: spark.sql.iceberg.vectorization.enabled=false
5. Set iceberg.engine.filters.enabled=false to avoid the filtered column-vector path

Example fix

// before: spark.conf.set("spark.sql.iceberg.vectorization.enabled","true") with deletes on nested columns
// after:
spark.conf.set("spark.sql.iceberg.vectorization.enabled", "false") // or rewrite files to clear deletes

// Check whether the scan will use the filtered vector path (delete files present)
Table table = sparkAdapter; // or:
// spark.sql("SELECT * FROM tbl.refs"); // inspect snapshots for delete files before nested projections

try {
  df.select("nested.field").collect();
} catch (UnsupportedOperationException e) {
  if (e.getMessage().startsWith("Unsupported nested type:")) {
    spark.conf.set("spark.sql.iceberg.vectorization.enabled", "false"); // retry unvectorized
  } else throw e;
}

When it happens

Trigger: A vectorized Spark read with row-level filters (delete files / positional deletes producing a rowIdMapping) where a requested child column's parent type is a nested type other than struct/array/map — e.g. filtered access into a nested column of an unsupported container.

Common situations: Reading tables with delete files where the query projects nested fields of an exotic type; newer Spark versions introducing a nested ColumnVector type this wrapper doesn't handle; version skew between Spark and the Iceberg Spark runtime.

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

• Unsupported nested type: ${dataType}
• Unsupported nested type: ${dataType()}
• Unsupported nested type:
• ${class} does not implement getArray
• Unsupported type: array

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