What causes "Unrecognized version or corrupt state: {version}" in apache/flink?

Ensure the bucket assigner and its serializer are the same between the job that wrote the checkpoint and the job restoring it.

apache/flink · error · IOException

Unrecognized version or corrupt state: {version}

Error message

Unrecognized version or corrupt state: {version}

What it means

Thrown by SimpleVersionedStringSerializer.deserialize when the version number is not 1. This serializer is used by bucket assigners (e.g. FlinkPartitionBucketAssigner) to serialize/deserialize bucket IDs; version 1 is the only supported format. Any other version indicates corruption or a version incompatibility.

Source

Thrown at flink-connectors/flink-file-sink-common/src/main/java/org/apache/flink/streaming/api/functions/sink/filesystem/bucketassigners/SimpleVersionedStringSerializer.java:61

    @Override
    public String deserialize(int version, byte[] serialized) throws IOException {
        switch (version) {
            case 1:
                return deserializeV1(serialized);
            default:
                throw new IOException("Unrecognized version or corrupt state: " + version);
        }
    }

View on GitHub (pinned to 2f3c205e92)

Solutions

Ensure the bucket assigner and its serializer are the same between the job that wrote the checkpoint and the job restoring it.
If the checkpoint is corrupt, restart from a previous known-good checkpoint.
Do not replace SimpleVersionedStringSerializer with a custom version-aware serializer without a migration path.

Defensive patterns

Strategy: try-catch

Try / catch

try {
    SimpleVersionedStringSerializer.INSTANCE.deserialize(version, bytes);
} catch (IOException e) {
    if (e.getMessage().startsWith("Unrecognized version or corrupt state")) {
        LOG.error("Bucket ID serializer received unexpected version {}", version);
    }
    throw e;
}

Prevention

Keep the same bucket assigner and serializer between checkpoint write and restore.
Do not replace SimpleVersionedStringSerializer with a custom versioned serializer without a migration plan.
Verify checkpoint integrity if corruption is suspected.

When it happens

Trigger: Restoring a checkpoint where the bucket ID string state was serialized with a version other than 1 by a different or newer serializer.

Common situations: Restoring a File Sink savepoint that was produced by a different bucket assigner or a modified SimpleVersionedStringSerializer; checkpoint corruption affecting the version byte.

Related errors

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