aeron-io/aeron · error · ClusterException

unexpected snapshot type

Error message

unexpected snapshot type: ${typeId}

What it means

ConsensusModuleSnapshotAdapter expects every snapshot stream to carry SNAPSHOT_TYPE_ID markers. A fragment inside the snapshot declared a different typeId, meaning the stream is not a valid consensus-module snapshot, so it refuses to load it.

Solutions

1. Verify the snapshotRecordingId in cluster mark file points to a genuine consensus-module snapshot recording
2. Restore from a known-good snapshot taken by the same cluster version
3. Check the archive catalog to confirm the recording type before replaying
4. Do not manually substitute recordings for snapshots

Example fix

// before
ClusterException: unexpected snapshot type: 1001
// after: point to the correct snapshot recording id or take a fresh snapshot
client.takeSnapshot(); // then restart from the new snapshotRecordingId

// Before replay, confirm the recording is a consensus-module snapshot
// check the recording's catalog entry / typeId metadata equals SNAPSHOT_TYPE_ID before pointing snapshotRecordingId at it

try {
    snapshotPlayer.load(recordingId, ...);
} catch (ClusterException e) {
    if (e.getMessage().startsWith("unexpected snapshot type")) {
        // fall back to a verified snapshot recording
        loadVerifiedSnapshot();
    } else { throw e; }
}

When it happens

Trigger: onFragment decodes a snapshotMarkerDecoder whose typeId() != SNAPSHOT_TYPE_ID — i.e. the recording being replayed as a snapshot contains other recording types (e.g. a raw log recording) or was produced by a different tool/version.

Common situations: Pointing the cluster at the wrong recording when restoring; snapshot replay of a recording that was extended or written by a custom entry type; corrupted or hand-edited archive catalogs.

Related errors

• snapshot ended unexpectedly
• snapshot ended unexpectedly
• expected schemaId= , actual=
• already in snapshot
• missing begin snapshot

AI-assisted analysis of aeron-io/aeron@6d60124e15 (2026-09-12). Data as JSON: /api/errors/269bee7687a4be41. Report an issue: GitHub.

Appendix: source

Thrown at aeron-cluster/src/main/java/io/aeron/cluster/ConsensusModuleSnapshotAdapter.java:97

                    buffer,
                    offset + MessageHeaderDecoder.ENCODED_LENGTH,
                    messageHeaderDecoder.blockLength(),
                    messageHeaderDecoder.version());

                listener.onLoadPendingMessage(sessionMessageHeaderDecoder.clusterSessionId(), buffer, offset, length);
                break;

            case SnapshotMarkerDecoder.TEMPLATE_ID:
                snapshotMarkerDecoder.wrap(
                    buffer,
                    offset + MessageHeaderDecoder.ENCODED_LENGTH,
                    messageHeaderDecoder.blockLength(),
                    messageHeaderDecoder.version());

                final long typeId = snapshotMarkerDecoder.typeId();
                if (SNAPSHOT_TYPE_ID != typeId)
                {
                    throw new ClusterException("unexpected snapshot type: " + typeId);
                }

                switch (snapshotMarkerDecoder.mark())
                {
                    case BEGIN:
                        if (inSnapshot)
                        {
                            throw new ClusterException("already in snapshot");
                        }
                        inSnapshot = true;

                        listener.onLoadBeginSnapshot(
                            snapshotMarkerDecoder.appVersion(),
                            ClusterClock.map(snapshotMarkerDecoder.timeUnit()),
                            buffer,
                            offset,
                            length);
                        return Action.CONTINUE;

View on GitHub (pinned to 6d60124e15)