apache/flink · critical · IOException

Corrupt data, magic number mismatch. Expected %8x, found %8x

Error message

Corrupt data, magic number mismatch. Expected %8x, found %8x

What it means

Thrown by NestedSerializersSnapshotDelegate.readNestedSerializerSnapshots when the magic-number integrity check fails — the first integer read from the stream does not equal MAGIC_NUMBER (1333245). This guards the nested-serializer-snapshots binary segment of a checkpoint/savepoint against corruption or misaligned reads. It is the integrity counterpart to the write path in writeNestedSerializerSnapshots.

Source

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

    // ------------------------------------------------------------------------

    /** Writes the composite snapshot of all the contained serializers. */
    public final void writeNestedSerializerSnapshots(DataOutputView out) throws IOException {
        out.writeInt(MAGIC_NUMBER);
        out.writeInt(VERSION);

        out.writeInt(nestedSnapshots.length);
        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);
        }

View on GitHub (pinned to 2f3c205e92)

Solutions

Verify the checkpoint/savepoint file integrity (size, checksums, completeness).
Ensure the restoring Flink version is compatible with the version that wrote the checkpoint.
If using a custom CompositeTypeSerializerSnapshot, confirm the order of internalReadOuterSnapshot and readNestedSerializerSnapshots calls matches the write order.
Re-create the checkpoint from a known-good savepoint if the file is confirmed corrupt.

Defensive patterns

Strategy: validation

Validate before calling

// Before restoring, verify checkpoint integrity (size, metadata completeness)
Path file = Path.of("/state/chk-42/db/");
if (!Files.exists(file)) {
    throw new IllegalStateException("State file not found: " + file);
}

Try / catch

try {
    backend.restore(checkpointPath);
} catch (IOException e) {
    if (e.getMessage().contains("magic number mismatch")) {
        log.error("Nested serializer snapshot data is corrupt or version-incompatible.");
    }
    throw e;
}

Prevention

Confirm checkpoint/savepoint files are fully written and not truncated before restore.
Restore with the same or compatible Flink version that wrote the checkpoint.
Audit custom CompositeTypeSerializerSnapshot read/write order for the nested delegate.

When it happens

Trigger: Reading a NestedSerializersSnapshotDelegate segment from a corrupt, truncated, or misaligned data stream. Attempting to read a stream whose position is wrong (e.g. reading nested snapshots where outer snapshot data is expected). A checkpoint file damaged by storage failure or incomplete write.

Common situations: Corrupted or partially-written checkpoint/savepoint files in HDFS/S3/local disk. Restoring state from a file that was not fully flushed. A custom CompositeTypeSerializerSnapshot that reads the nested delegate at the wrong offset. Version skew causing the reader to expect the magic number where different data sits.

Related errors

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