apache/seatunnel · error · java.lang.UnsupportedOperationException

Map as map key is not supported

Error message

Map as map key is not supported

What it means

MapTypeWriter.writeToMapKey rejects MAP values used as MAP keys. Arrow map key vectors support only flat, hashable scalar types; a nested map can never be a key. This method throws UnsupportedOperationException unconditionally as a guard.

Source

Thrown at seatunnel-connectors-v2/connector-lance/src/main/java/org/apache/seatunnel/connectors/seatunnel/lance/sink/writers/MapTypeWriter.java:47

            FieldVector vector,
            ArrowType arrowType,
            Object value,
            int rowIndex,
            BufferAllocator allocator) {
        throw new UnsupportedOperationException(
                "Map type should be handled via FragmentConverter.writeMapToVector");
    }

    @Override
    public void writeToListWriter(
            UnionListWriter writer, ArrowType arrowType, Object value, BufferAllocator allocator) {
        throw new UnsupportedOperationException("Map in list writing not yet implemented");
    }

    @Override
    public void writeToMapKey(
            UnionMapWriter writer, ArrowType arrowType, Object value, BufferAllocator allocator) {
        throw new UnsupportedOperationException("Map as map key is not supported");
    }

    @Override
    public void writeToMapValue(
            UnionMapWriter writer, ArrowType arrowType, Object value, BufferAllocator allocator) {
        throw new UnsupportedOperationException("Map as map value not yet implemented");
    }
}

View on GitHub (pinned to cf67b549a7)

Solutions

  1. Use a scalar key type (STRING/INT) in the map schema.
  2. Encode a composite key as a canonical string (e.g. JSON or delimited concatenation of the nested map).
  3. Restructure as LIST<STRUCT<key, value>> where the 'key' can itself be a struct.
  4. Add a pre-write schema validation step that asserts map key types are scalar.

Example fix

// before
columns = "data map<map<string,string>, int>"

// after: string-encoded key
columns = "data map<string, int>"  // key = JSON string of inner map
Defensive patterns

Strategy: validation

Validate before calling

// Java: assert map key type is not a nested map
ArrowType keyType = mapField.getChildren().get(0).getType();
if (keyType instanceof ArrowType.Map) {
    throw new IllegalArgumentException("map keys must be scalar, not map");
}

Type guard

boolean isScalarKey(ArrowType t) {
    return !(t instanceof ArrowType.Map) && !(t instanceof ArrowType.List);
}

Prevention

When it happens

Trigger: A SeaTunnel MAP field declared with MAP as its key type (map<map<...>, V>); during entry writing the key dispatch reaches MapTypeWriter.writeToMapKey.

Common situations: Deeply nested schema modeling mistakes; programmatic schema generation that accidentally nests maps; porting data from systems that allow struct-like keys.

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/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/189755d58c3ae341. Report an issue: GitHub.