{"record":{"id":"edc329125b324047","repo":"apache/flink","slug":"unexpected-serializer-type","errorCode":null,"errorMessage":"Unexpected serializer type.","messagePattern":"Unexpected serializer type\\.","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"flink-core/src/main/java/org/apache/flink/api/common/state/MapStateDescriptor.java","lineNumber":105,"sourceCode":"     */\n    public MapStateDescriptor(String name, Class<UK> keyClass, Class<UV> valueClass) {\n        super(name, new MapTypeInfo<>(keyClass, valueClass), null);\n    }\n\n    @Override\n    public Type getType() {\n        return Type.MAP;\n    }\n\n    /**\n     * Gets the serializer for the keys in the state.\n     *\n     * @return The serializer for the keys in the state.\n     */\n    public TypeSerializer<UK> getKeySerializer() {\n        final TypeSerializer<Map<UK, UV>> rawSerializer = getSerializer();\n        if (!(rawSerializer instanceof MapSerializer)) {\n            throw new IllegalStateException(\"Unexpected serializer type.\");\n        }\n\n        return ((MapSerializer<UK, UV>) rawSerializer).getKeySerializer();\n    }\n\n    /**\n     * Gets the serializer for the values in the state.\n     *\n     * @return The serializer for the values in the state.\n     */\n    public TypeSerializer<UV> getValueSerializer() {\n        final TypeSerializer<Map<UK, UV>> rawSerializer = getSerializer();\n        if (!(rawSerializer instanceof MapSerializer)) {\n            throw new IllegalStateException(\"Unexpected serializer type.\");\n        }\n\n        return ((MapSerializer<UK, UV>) rawSerializer).getValueSerializer();\n    }","sourceCodeStart":87,"sourceCodeEnd":123,"githubUrl":"https://github.com/apache/flink/blob/2f3c205e9266cb30240eb7f4fdab15cad629a70f/flink-core/src/main/java/org/apache/flink/api/common/state/MapStateDescriptor.java#L87-L123","documentation":"Thrown by MapStateDescriptor.getKeySerializer() when the state's serializer is not a MapSerializer. The method assumes the underlying serializer wraps a key serializer and a value serializer; if a custom or incompatible serializer was injected (e.g. via setStateSerializer or a config override), the cast to MapSerializer would be unsafe, so an explicit instanceof guard throws instead. This indicates the state descriptor's serializer was replaced after construction.","triggerScenarios":"Calling getKeySerializer() after the descriptor's serializer was overridden with a non-MapSerializer (e.g. a custom TypeSerializer injected via a StateBackend config or a restore from a savepoint with an incompatible serializer snapshot).","commonSituations":"Restoring a MapState from a savepoint whose serializer snapshot resolved to a non-map serializer; injecting a custom serializer via the state backend configuration; using a state backend that substitutes serializers internally.","solutions":["Ensure the MapStateDescriptor uses the default MapSerializer (do not override the serializer for map state).","If restoring from a savepoint, verify the serializer snapshot is compatible with MapSerializer or re-register the correct serializer.","If you need a custom serializer, access the raw serializer via getSerializer() instead of getKeySerializer()."],"exampleFix":"// before: custom serializer override breaks getKeySerializer\ndescriptor.initializeSerializerUnlessSet(() -> new CustomTypeSerializer<>());\ndescriptor.getKeySerializer(); // throws IllegalStateException\n\n// after: let the descriptor build its own MapSerializer\ndescriptor.getKeySerializer(); // returns MapSerializer's key serializer","handlingStrategy":"type-guard","validationCode":"TypeSerializer<?> ser = descriptor.getSerializer();\nif (!(ser instanceof MapSerializer)) {\n    throw new IllegalStateException(\n        \"Cannot get key serializer: underlying serializer is \" + ser.getClass().getName());\n}","typeGuard":"public static boolean hasMapSerializer(MapStateDescriptor<?, ?> desc) {\n    return desc.getSerializer() instanceof MapSerializer;\n}","tryCatchPattern":"try {\n    return descriptor.getKeySerializer();\n} catch (IllegalStateException e) {\n    // fall back to raw serializer access\n    return descriptor.getSerializer();\n}","preventionTips":["Do not override the serializer on MapStateDescriptor; let it build MapSerializer.","On savepoint restore, verify serializer compatibility before accessing key/value serializers.","Use getSerializer() if you inject a custom non-map serializer."],"tags":["state","serialization","map-state","serializer"],"backgroundTag":null,"analyzedSha":"2f3c205e9266cb30240eb7f4fdab15cad629a70f","analyzedAt":"2026-08-14T08:48:24.518Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}