apache/flink · error · IllegalStateException

unrecognized compatibility type.

Error message

unrecognized compatibility type.

What it means

Thrown by IntermediateCompatibilityResult.asFinalCompatibilityResult in the default branch of a switch on TypeSerializerSchemaCompatibility.Type. Only COMPATIBLE_AS_IS, COMPATIBLE_AFTER_MIGRATION, and INCOMPATIBLE are handled (COMPATIBLE_WITH_RECONFIGURED_SERIALIZER is guarded by a precondition check earlier). Reaching the default means the internal compatibility-type enum has a value the code does not know about — a sign of a version mismatch between flink-core modules or an internal bug.

Source

Thrown at flink-core/src/main/java/org/apache/flink/api/common/typeutils/CompositeTypeSerializerUtil.java:205

        public boolean isIncompatible() {
            return compatibilityType == TypeSerializerSchemaCompatibility.Type.INCOMPATIBLE;
        }

        public TypeSerializerSchemaCompatibility<T> getFinalResult() {
            checkState(
                    compatibilityType
                            != TypeSerializerSchemaCompatibility.Type
                                    .COMPATIBLE_WITH_RECONFIGURED_SERIALIZER,
                    "unable to build final result if intermediate compatibility type is COMPATIBLE_WITH_RECONFIGURED_SERIALIZER.");
            switch (compatibilityType) {
                case COMPATIBLE_AS_IS:
                    return TypeSerializerSchemaCompatibility.compatibleAsIs();
                case COMPATIBLE_AFTER_MIGRATION:
                    return TypeSerializerSchemaCompatibility.compatibleAfterMigration();
                case INCOMPATIBLE:
                    return TypeSerializerSchemaCompatibility.incompatible();
                default:
                    throw new IllegalStateException("unrecognized compatibility type.");
            }
        }

        public TypeSerializer<?>[] getNestedSerializers() {
            checkState(
                    compatibilityType == TypeSerializerSchemaCompatibility.Type.COMPATIBLE_AS_IS
                            || compatibilityType
                                    == TypeSerializerSchemaCompatibility.Type
                                            .COMPATIBLE_WITH_RECONFIGURED_SERIALIZER,
                    "only intermediate compatibility types COMPATIBLE_AS_IS and COMPATIBLE_WITH_RECONFIGURED_SERIALIZER have nested serializers.");
            return nestedSerializers;
        }
    }

    @SuppressWarnings("unchecked")
    private static <E> TypeSerializerSchemaCompatibility<E> resolveCompatibility(
            TypeSerializerSnapshot<?> newSnapshot, TypeSerializerSnapshot<?> oldSnapshot) {

View on GitHub (pinned to 2f3c205e92)

Solutions

  1. Ensure all Flink modules on the classpath share the exact same version (check dependency tree with mvn dependency:tree).
  2. Remove conflicting transitive Flink dependencies or use a BOM/dependencyManagement to pin one version.
  3. If running a custom Flink fork, update this switch to handle any new TypeSerializerSchemaCompatibility.Type constant.
Defensive patterns

Strategy: try-catch

Validate before calling

// Verify no version skew across Flink modules before deploying
// mvn dependency:tree -Dincludes=org.apache.flink  should show ONE version everywhere

Try / catch

try {
    backend.restore(state);
} catch (IllegalStateException e) {
    if (e.getMessage().contains("unrecognized compatibility type")) {
        log.error("Flink module version skew detected. Align all flink-* JARs to one version.");
    }
    throw e;
}

Prevention

When it happens

Trigger: An internal code path constructs an IntermediateCompatibilityResult with a compatibilityType that is not one of the three handled cases. This is effectively impossible with stock Flink unless there is a module version skew (e.g. flink-core from one Flink minor version mixed with flink-runtime from another) or bytecode manipulation introduced a new enum constant.

Common situations: Mixed Flink JAR versions on the classpath (e.g. flink-core 1.18 with flink-runtime 1.17). A shaded/relocated Flink dependency that altered the enum. A bug in a custom fork of Flink that added an enum constant without updating this switch.

Related errors

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