apache/flink · critical · IllegalStateException

Failed to Java-Deserialize an AvroSerializer instance. Was e

Error message

Failed to Java-Deserialize an AvroSerializer instance. Was expecting a first field to be either a String or SerializableAvroSchema, but got: %s

What it means

IllegalStateException from AvroSerializer's Java-deserialization readObject when restoring serializer state: the first deserialized field is neither String (Flink 1.6 layout), Class (1.5 layout), nor SerializableAvroSchema (current layout). This indicates corrupted state bytes or bytes written by an incompatible/unknown Flink version.

Source

Thrown at flink-formats/flink-avro/src/main/java/org/apache/flink/formats/avro/typeutils/AvroSerializer.java:413

        TypeSerializers)
        */
        final Object firstField = in.readObject();

        if (firstField == null) {
            // first field can only be NULL in 1.6 (schemaString)
            read16Layout(null, in);
        } else if (firstField instanceof String) {
            // first field is a String only in 1.6 (schemaString)
            read16Layout((String) firstField, in);
        } else if (firstField instanceof Class<?>) {
            // first field is a Class<?> only in 1.5 (type)
            @SuppressWarnings("unchecked")
            Class<T> type = (Class<T>) firstField;
            read15Layout(type);
        } else if (firstField instanceof SerializableAvroSchema) {
            readCurrentLayout((SerializableAvroSchema) firstField, in);
        } else {
            throw new IllegalStateException(
                    "Failed to Java-Deserialize an AvroSerializer instance. "
                            + "Was expecting a first field to be either a String or SerializableAvroSchema, but got: "
                            + ""
                            + firstField.getClass());
        }
    }

    private void read15Layout(Class<T> type) {
        this.previousSchema = new SerializableAvroSchema();
        this.schema = new SerializableAvroSchema();
        this.type = type;
    }

    @SuppressWarnings("unchecked")
    private void read16Layout(@Nullable String schemaString, ObjectInputStream in)
            throws IOException, ClassNotFoundException {

        Schema schema = AvroFactory.parseSchemaString(schemaString);

View on GitHub (pinned to 2f3c205e92)

Solutions

Restore stepwise through supported upgrade paths (each Flink version only guarantees reading the previous format).
Verify checkpoint/savepoint integrity (file sizes, no partial uploads).
If the state origin is unknown, treat the state as unrecoverable and rebuild from source data.
Report to Flink dev mailing list with the writing and reading Flink versions.

Defensive patterns

Strategy: try-catch

Try / catch

try {
    env.execute(); // restore path
} catch (IllegalStateException e) {
    if (e.getMessage().contains("Failed to Java-Deserialize an AvroSerializer")) {
        // state written by unsupported version: do not blindly restart; verify origin Flink version
        log.error("Incompatible AvroSerializer state layout; state must be re-created", e);
    }
    throw e;
}

Prevention

Upgrade Flink one major version at a time so serializer layouts stay readable.
Keep records of which Flink version wrote each savepoint.
Store checkpoints on durable storage with checksums; discard partial uploads.

When it happens

Trigger: Restoring a checkpoint/savepoint whose AvroSerializer snapshot stream was written by a Flink version with an unrecognized serialized layout; truncated or corrupted state files; manually constructed stream data.

Common situations: Restoring old savepoints across multiple major Flink upgrades at once; state files damaged by interrupted writes or filesystem issues.

Related errors

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