apache/flink · critical · IOException

Unrecognized version

Error message

Unrecognized version: {}

What it means

Thrown by NestedSerializersSnapshotDelegate.readNestedSerializerSnapshots when the version integer read after the magic number does not equal the current VERSION constant (1). This means the serialized nested-snapshots segment was written by a format revision the running Flink version does not understand, or the stream is corrupt and the version field holds garbage.

Solutions

1. Restore with the Flink version that wrote the checkpoint, then re-save if you need to migrate.
2. Follow the Flink upgrade path (only restore from compatible versions; check the state compatibility docs for your versions).
3. If the file is corrupt (not a version issue), re-take the checkpoint from a good state.
4. Verify there is no accidental double-read of the stream causing misalignment.

// Verify Flink version compatibility before restore (documented upgrade path)
// Ensure the writing version and restoring version share NestedSerializersSnapshotDelegate.VERSION

try {
    backend.restore(checkpointPath);
} catch (IOException e) {
    if (e.getMessage().contains("Unrecognized version")) {
        log.error("Checkpoint written by an incompatible Flink version. Restore with the original version first.");
    }
    throw e;
}

When it happens

Trigger: Restoring a checkpoint/savepoint written by a newer Flink version that incremented the NestedSerializersSnapshotDelegate VERSION. Reading corrupt data where the version integer is a random value. A custom serialization format that reused this delegate's binary layout with a different version scheme.

Common situations: Upgrading Flink and attempting to restore an old checkpoint whose nested-snapshot format predates the current version (if a legacy read path is missing). Downgrading Flink and reading a checkpoint written by a newer format. File corruption producing a bogus version integer.

Related errors

• Unrecognized version
• Unrecognized version for TypeSerializerSnapshot format
• Corrupt data, magic number mismatch. Expected %8x, found %8x
• Corrupt data, magic number mismatch. Expected %8x, found %8x
• This object is a dummy TypeSerializer.

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

Appendix: source

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

        for (TypeSerializerSnapshot<?> snap : nestedSnapshots) {
            TypeSerializerSnapshot.writeVersionedSnapshot(out, snap);
        }
    }

    /** Reads the composite snapshot of all the contained serializers. */
    public static NestedSerializersSnapshotDelegate readNestedSerializerSnapshots(
            DataInputView in, ClassLoader cl) throws IOException {
        final int magicNumber = in.readInt();
        if (magicNumber != MAGIC_NUMBER) {
            throw new IOException(
                    String.format(
                            "Corrupt data, magic number mismatch. Expected %8x, found %8x",
                            MAGIC_NUMBER, magicNumber));
        }

        final int version = in.readInt();
        if (version != VERSION) {
            throw new IOException("Unrecognized version: " + version);
        }

        final int numSnapshots = in.readInt();
        final TypeSerializerSnapshot<?>[] nestedSnapshots =
                new TypeSerializerSnapshot<?>[numSnapshots];

        for (int i = 0; i < numSnapshots; i++) {
            nestedSnapshots[i] = TypeSerializerSnapshot.readVersionedSnapshot(in, cl);
        }

        return new NestedSerializersSnapshotDelegate(nestedSnapshots);
    }

    // ------------------------------------------------------------------------
    //  Utilities
    // ------------------------------------------------------------------------

    private static TypeSerializer<?>[] snapshotsToRestoreSerializers(

View on GitHub (pinned to 2f3c205e92)