apache/flink · critical · IllegalArgumentException

unknown snapshot version for AvroSerializerSnapshot %s

Error message

unknown snapshot version for AvroSerializerSnapshot %s

What it means

IllegalArgumentException from AvroSerializerSnapshot.read when the snapshot's version int is not 1, 2, or 3. The serialized snapshot format is unrecognized — either corrupted state or a snapshot written by an incompatible Flink version.

Source

Thrown at flink-formats/flink-avro/src/main/java/org/apache/flink/formats/avro/typeutils/AvroSerializerSnapshot.java:101

            throws IOException {
        switch (readVersion) {
            case 1:
                {
                    readV1(in, userCodeClassLoader);
                    return;
                }
            case 2:
                {
                    readV2(in, userCodeClassLoader);
                    return;
                }
            case 3:
                {
                    readV3(in, userCodeClassLoader);
                    return;
                }
            default:
                throw new IllegalArgumentException(
                        "unknown snapshot version for AvroSerializerSnapshot " + readVersion);
        }
    }

    private void readV1(DataInputView in, ClassLoader userCodeClassLoader) throws IOException {
        final String previousSchemaDefinition = in.readUTF();
        this.schema = parseAvroSchema(previousSchemaDefinition);
        this.runtimeType = findClassOrFallbackToGeneric(userCodeClassLoader, schema.getFullName());
        this.runtimeSchema = tryExtractAvroSchema(userCodeClassLoader, runtimeType);
    }

    private void readV2(DataInputView in, ClassLoader userCodeClassLoader) throws IOException {
        final String previousRuntimeTypeName = in.readUTF();
        final String previousSchemaDefinition = in.readUTF();

        this.runtimeType = findClassOrThrow(userCodeClassLoader, previousRuntimeTypeName);
        this.schema = parseAvroSchema(previousSchemaDefinition);
        this.runtimeSchema = tryExtractAvroSchema(userCodeClassLoader, runtimeType);

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Confirm the Flink version that wrote the state matches a supported upgrade path (upgrade one major version at a time).
2. Ensure a single consistent Flink distribution on the classpath (no mixed jars).
3. If corruption is confirmed, discard the checkpoint and restore from upstream data / new snapshot.

try {
    env.execute();
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("unknown snapshot version")) {
        // unsupported or corrupted snapshot: rebuild state instead of retrying
        log.error("Unrecognized AvroSerializerSnapshot version; cannot restore", e);
    }
    throw e;
}

When it happens

Trigger: Restoring a checkpoint containing an AvroSerializerSnapshot with an unknown leading version int; reading arbitrary bytes as state; version-skipping upgrades (e.g. 1.3 savepoint into 1.15+).

Common situations: Corrupted checkpoint files due to job kill during write; restoring very old savepoints beyond the supported migration window; classpath mixing Flink jars of different versions.

Related errors

• Failed to Java-Deserialize an AvroSerializer instance. Was e
• Unable to find the class '%s' which is used to deserialize t
• Unrecognized version or corrupt state: {version}
• Schema must be set when using Generic Record
• Failed to deserialize Avro record.

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