apache/flink · critical · IOException

The bytes are serialized with version %d, while this deseria

Error message

The bytes are serialized with version %d, while this deserializer only supports version up to %d

What it means

Thrown as an IOException by HybridSourceEnumeratorStateSerializer.deserialize when the serialized state version is not 0 (CURRENT_VERSION). The serializer only supports version 0; any other version indicates the state was produced by a future or incompatible version of HybridSourceEnumeratorStateSerializer. This is a forward-compatibility guard: the deserializer refuses to process bytes it cannot safely interpret.

Source

Thrown at flink-connectors/flink-connector-base/src/main/java/org/apache/flink/connector/base/source/hybrid/HybridSourceEnumeratorStateSerializer.java:61

    public byte[] serialize(HybridSourceEnumeratorState enumState) throws IOException {
        try (ByteArrayOutputStream baos = new ByteArrayOutputStream();
                DataOutputStream out = new DataOutputStream(baos)) {
            out.writeInt(enumState.getCurrentSourceIndex());
            out.writeInt(enumState.getWrappedStateSerializerVersion());
            out.writeInt(enumState.getWrappedState().length);
            out.write(enumState.getWrappedState());
            out.flush();
            return baos.toByteArray();
        }
    }

    @Override
    public HybridSourceEnumeratorState deserialize(int version, byte[] serialized)
            throws IOException {
        if (version == 0) {
            return deserializeV0(serialized);
        }
        throw new IOException(
                String.format(
                        "The bytes are serialized with version %d, "
                                + "while this deserializer only supports version up to %d",
                        version, CURRENT_VERSION));
    }

    private HybridSourceEnumeratorState deserializeV0(byte[] serialized) throws IOException {
        try (ByteArrayInputStream bais = new ByteArrayInputStream(serialized);
                DataInputStream in = new DataInputStream(bais)) {
            int sourceIndex = in.readInt();
            int nestedVersion = in.readInt();
            int length = in.readInt();
            byte[] nestedBytes = new byte[length];
            in.readFully(nestedBytes);
            return new HybridSourceEnumeratorState(sourceIndex, nestedBytes, nestedVersion);
        }
    }
}

View on GitHub (pinned to 2f3c205e92)

Solutions

Upgrade the Flink client and cluster to the version that produced the checkpoint (matching or newer serializer version).
If downgrading is required, start the job from scratch without restoring the HybridSource enumerator state.
Never downgrade across versions that change the HybridSource state serializer format.
Check the Flink release notes for HybridSource state serializer version changes before upgrading.

Defensive patterns

Strategy: validation

Validate before calling

// Check serializer version compatibility before deserializing
int stateVersion = HybridSourceEnumeratorStateSerializer.INSTANCE.getVersion();
if (checkpointVersion > stateVersion) {
    throw new IllegalStateException(
        "Cannot restore: checkpoint was serialized with version " + checkpointVersion
        + " but this serializer only supports up to version " + stateVersion);
}

Try / catch

try {
    HybridSourceEnumeratorState state = serializer.deserialize(version, bytes);
} catch (IOException e) {
    if (e.getMessage().contains("only supports version up to")) {
        // version mismatch — upgrade Flink or start fresh
        log.error("State version mismatch: {}", e.getMessage());
    }
}

Prevention

Never downgrade Flink across versions that change the HybridSource state serializer.
Check the serializer version in release notes before upgrading.
Take a fresh checkpoint after upgrading if state format changed.

When it happens

Trigger: Restoring a HybridSource enumerator state from a checkpoint/savepoint produced by a newer Flink version that uses a higher serializer version (version > 0).

Common situations: Upgrading Flink to a version that bumped HybridSourceEnumeratorStateSerializer.getVersion(), then trying to restore an old client/deserializer against the newer checkpoint; downgrade scenario where a newer checkpoint is loaded by an older Flink version.

Related errors

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