apache/flink · error · VersionMismatchException

Incompatible version: found {}, compatible versions are {}

Error message

Incompatible version: found {}, compatible versions are {}

What it means

Thrown as a VersionMismatchException by VersionedIOReadableWritable.resolveVersionRead when the version integer read from the stream does not appear in the getCompatibleVersions() array. By default only the current getVersion() is compatible, but subclasses can widen this. This guard prevents deserializing data written by an incompatible serialization version, which could produce corrupt objects.

Source

Thrown at flink-core/src/main/java/org/apache/flink/core/io/VersionedIOReadableWritable.java:100

        for (int compatibleVersion : compatibleVersions) {
            if (compatibleVersion == readVersion) {
                return;
            }
        }

        String error =
                "Incompatible version: found "
                        + readVersion
                        + ", compatible versions are "
                        + Arrays.toString(compatibleVersions);

        Optional<String> incompatibleVersionError =
                getAdditionalDetailsForIncompatibleVersion(readVersion);
        if (incompatibleVersionError.isPresent()) {
            error += ". " + incompatibleVersionError.get();
        }

        throw new VersionMismatchException(error);
    }
}

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Check the Flink version that wrote the data against the version reading it; upgrade rather than downgrade if versions diverge.
2. If you control the serializer subclass, override getCompatibleVersions() to include the older version.
3. Override getAdditionalDetailsForIncompatibleVersion to provide migration guidance.
4. If incompatible, discard the old state and re-create from a fresh savepoint.

Example fix

// before — only current version accepted
@Override public int[] getCompatibleVersions() { return new int[]{getVersion()}; }

// after — accept legacy versions
@Override public int[] getCompatibleVersions() { return new int[]{getVersion(), 1, 2}; }

int[] compatible = obj.getCompatibleVersions();
boolean ok = false;
for (int v : compatible) if (v == expectedReadVersion) { ok = true; break; }
if (!ok) throw new VersionMismatchException("Version " + expectedReadVersion + " not compatible");

try {
    obj.read(in);
} catch (VersionMismatchException e) {
    // check for downgrade incompatibility; upgrade or re-create state
}

When it happens

Trigger: Reading serialized data whose embedded version is not in the compatible set; data written by a newer Flink version read by an older one; data written by a different serializer implementation altogether.

Common situations: Downgrading Flink and restoring a checkpoint/savepoint written by a newer version; cross-version state incompatibility; serializer refactoring that changed the version number without adding backward compatibility.

Related errors

• Invalid version %d
• Unrecognized version or corrupt state: {}
• Serialized data with version %d cannot be read by serializer
• The bytes are serialized with version %d, while this deseria
• Unrecognized version or corrupt state: {version}

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