aeron-io/aeron · error · ClusterException

missing begin snapshot

Error message

missing begin snapshot

What it means

An END snapshot marker arrived when no BEGIN marker had been seen (inSnapshot == false). Snapshot loading is stateful: END is only valid after BEGIN, so the adapter treats the stream as malformed and aborts.

Solutions

1. Replay the snapshot recording from its beginning (position 0), not from a mid-stream position
2. Restore a complete snapshot recording from backup
3. Re-take a snapshot on the leader and use its recordingId
4. Check archive segments for deletion/trimming of early frames

Example fix

// before
archive.startReplay(recordingId, midStreamPosition, ...)
// after
archive.startReplay(recordingId, 0L, ...); // replay the full snapshot from the start

// Ensure replay starts at recording position 0 and that the earliest archive segment still exists
long startPosition = 0L; // never a mid-stream position for snapshot replay

try {
    snapshotPlayer.load(recordingId, ...);
} catch (ClusterException e) {
    if ("missing begin snapshot".equals(e.getMessage())) {
        // recording truncated at the start — use backup
        restoreFromBackup();
    } else { throw e; }
}

When it happens

Trigger: Replaying a recording whose snapshot markers are out of order or truncated at the start — e.g. the first fragment(s) with the BEGIN marker were lost, or the recording starts mid-snapshot.

Common situations: Replaying a recording trimmed/segmented so the snapshot header is missing; archive catalog pointing to a partial recording; replay starting at a non-zero position.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• snapshot ended unexpectedly
• snapshot ended unexpectedly
• expected schemaId= , actual=
• unexpected snapshot type
• already in snapshot

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

Appendix: source

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

                    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;

                    case END:
                        if (!inSnapshot)
                        {
                            throw new ClusterException("missing begin snapshot");
                        }
                        listener.onLoadEndSnapshot(buffer, offset, length);
                        isDone = true;
                        return Action.BREAK;

                    case SECTION:
                    case NULL_VAL:
                        break;
                }
                break;

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

View on GitHub (pinned to 6d60124e15)