apache/flink · error · UnsupportedOperationException

Avro format doesn't support non-string as key type of map. T

Error message

Avro format doesn't support non-string as key type of map. The key type is: %s

What it means

UnsupportedOperationException from extractValueTypeToAvroMap when a Flink MAP's key type (or MULTISET element type) is not in the CHARACTER_STRING family. Avro map keys are always strings, so maps keyed by INT, BIGINT, etc. cannot be converted to an Avro schema.

Source

Thrown at flink-formats/flink-avro/src/main/java/org/apache/flink/formats/avro/typeutils/AvroSchemaConverter.java:598

                throw new UnsupportedOperationException(
                        "Unsupported to derive Schema for type: " + logicalType);
        }
    }

    public static LogicalType extractValueTypeToAvroMap(LogicalType type) {
        LogicalType keyType;
        LogicalType valueType;
        if (type instanceof MapType) {
            MapType mapType = (MapType) type;
            keyType = mapType.getKeyType();
            valueType = mapType.getValueType();
        } else {
            MultisetType multisetType = (MultisetType) type;
            keyType = multisetType.getElementType();
            valueType = new IntType();
        }
        if (!keyType.is(LogicalTypeFamily.CHARACTER_STRING)) {
            throw new UnsupportedOperationException(
                    "Avro format doesn't support non-string as key type of map. "
                            + "The key type is: "
                            + keyType.asSummaryString());
        }
        return valueType;
    }

    /** Returns schema with nullable true. */
    private static Schema nullableSchema(Schema schema) {
        return schema.isNullable()
                ? schema
                : Schema.createUnion(SchemaBuilder.builder().nullType(), schema);
    }
}

View on GitHub (pinned to 2f3c205e92)

Solutions

Change the key type to VARCHAR/STRING (convert keys to strings upstream or via a computed column).
Model the mapping as ARRAY<ROW<key ..., value ...>> which supports any key type.

Example fix

-- before
id_to_name MAP<BIGINT, STRING>,

-- after
id_to_name MAP<STRING, STRING>,
-- or
id_to_name ARRAY<ROW<id BIGINT, name STRING>>,
-- or (multiset is string-family)
id_counts MULTISET<STRING>,

Defensive patterns

Strategy: validation

Validate before calling

import org.apache.flink.table.types.logical.MapType;
import org.apache.flink.table.types.logical.LogicalTypeFamily;

boolean avroConvertible(MapType m) {
    return m.getKeyType().is(LogicalTypeFamily.CHARACTER_STRING);
}

Type guard

boolean hasStringKeys(MapType m) { return m.getKeyType().is(LogicalTypeFamily.CHARACTER_STRING); }

Prevention

Model non-string keyed mappings as ARRAY<ROW<k ..., v ...>> in avro tables.
Stringify map keys at the source or in a computed column before the sink.

When it happens

Trigger: convertToSchema on MAP<INT, ...> or MAP<BIGINT, ...>; MULTISET<INT>; an avro-format table declaring a map column with a non-string key.

Common situations: Schemas with id-to-value maps (e.g. MAP<BIGINT, STRING>) coming from JSON/Kafka sources where non-string keys are legal.

Related errors

AI-assisted analysis of apache/flink@2f3c205e92 (2026-08-14). Data as JSON: /api/errors/410817d75749ed4e. Report an issue: GitHub.