apache/iceberg · error · IllegalArgumentException

Expected two ORC type descriptions for a map, got: {orcTypes

Error message

Expected two ORC type descriptions for a map, got: {orcTypes}

What it means

SparkOrcValueWriters.MapWriter expects exactly two ORC TypeDescriptions — one for keys and one for values. If orcTypes.size() != 2 the provided type list does not match a map's layout, so the constructor throws IllegalArgumentException, preventing key/value getters from reading the wrong child types.

Source

Thrown at spark/v4.1/spark/src/main/java/org/apache/iceberg/spark/data/SparkOrcValueWriters.java:178

    @Override
    public Stream<FieldMetrics<?>> metrics() {
      return writer.metrics();
    }
  }

  private static class MapWriter<K, V> implements OrcValueWriter<MapData> {
    private final OrcValueWriter<K> keyWriter;
    private final OrcValueWriter<V> valueWriter;
    private final SparkOrcWriter.FieldGetter<K> keyFieldGetter;
    private final SparkOrcWriter.FieldGetter<V> valueFieldGetter;

    @SuppressWarnings("unchecked")
    MapWriter(
        OrcValueWriter<K> keyWriter,
        OrcValueWriter<V> valueWriter,
        List<TypeDescription> orcTypes) {
      if (orcTypes.size() != 2) {
        throw new IllegalArgumentException(
            "Expected two ORC type descriptions for a map, got: " + orcTypes);
      }
      this.keyWriter = keyWriter;
      this.valueWriter = valueWriter;
      this.keyFieldGetter =
          (SparkOrcWriter.FieldGetter<K>) SparkOrcWriter.createFieldGetter(orcTypes.get(0));
      this.valueFieldGetter =
          (SparkOrcWriter.FieldGetter<V>) SparkOrcWriter.createFieldGetter(orcTypes.get(1));
    }

    @Override
    public void nonNullWrite(int rowId, MapData map, ColumnVector output) {
      ArrayData key = map.keyArray();
      ArrayData value = map.valueArray();
      MapColumnVector cv = (MapColumnVector) output;
      // record the length and start of the list elements
      cv.lengths[rowId] = value.numElements();
      cv.offsets[rowId] = cv.childCount;

View on GitHub (pinned to 86d9c8fc54)

Solutions

Pass exactly the two child TypeDescriptions (key, value) of the ORC map
Confirm with record.getChildren() that the map column has two children
Fix the schema-mapping code that assembles orcTypes
Upgrade Iceberg if this stems from a known mapping bug

Defensive patterns

Strategy: try-catch

Validate before calling

List<TypeDescription> children = mapType.getChildren();
if (children.size() != 2) {
  throw new IllegalStateException("Map column must have key+value types, got: " + children.size());
}

Try / catch

try {
  new SparkOrcValueWriters.MapWriter<>(kw, vw, orcTypes);
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("for a map")) { /* pass exactly key and value TypeDescriptions */ }
  else throw e;
}

Prevention

Pass exactly mapType.getChildren() (2 entries) to MapWriter
Verify ORC schema layout with TypeDescription.print() during development
Keep schema-mapping code covered with nested map tests

When it happens

Trigger: Constructing a MapWriter with a child type list that is not exactly [keyType, valueType] — e.g. passing flattened struct children or an empty list due to a schema-mapping bug.

Common situations: Custom ORC writer plumbing passing the wrong TypeDescription children; ORC files with non-standard map encoding; mapping code desynced from the ORC file's actual schema.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

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