{"record":{"id":"eafcd8156922c4a7","repo":"aeron-io/aeron","slug":"missing-begin-snapshot","errorCode":null,"errorMessage":"missing begin snapshot","messagePattern":"missing begin snapshot","errorType":"exception","errorClass":"ClusterException","httpStatus":null,"severity":"error","filePath":"aeron-cluster/src/main/java/io/aeron/cluster/ConsensusModuleSnapshotAdapter.java","lineNumber":120,"sourceCode":"                    case BEGIN:\n                        if (inSnapshot)\n                        {\n                            throw new ClusterException(\"already in snapshot\");\n                        }\n                        inSnapshot = true;\n\n                        listener.onLoadBeginSnapshot(\n                            snapshotMarkerDecoder.appVersion(),\n                            ClusterClock.map(snapshotMarkerDecoder.timeUnit()),\n                            buffer,\n                            offset,\n                            length);\n                        return Action.CONTINUE;\n\n                    case END:\n                        if (!inSnapshot)\n                        {\n                            throw new ClusterException(\"missing begin snapshot\");\n                        }\n                        listener.onLoadEndSnapshot(buffer, offset, length);\n                        isDone = true;\n                        return Action.BREAK;\n\n                    case SECTION:\n                    case NULL_VAL:\n                        break;\n                }\n                break;\n\n            case ClusterSessionDecoder.TEMPLATE_ID:\n                clusterSessionDecoder.wrap(\n                    buffer,\n                    offset + MessageHeaderDecoder.ENCODED_LENGTH,\n                    messageHeaderDecoder.blockLength(),\n                    messageHeaderDecoder.version());\n","sourceCodeStart":102,"sourceCodeEnd":138,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-cluster/src/main/java/io/aeron/cluster/ConsensusModuleSnapshotAdapter.java#L102-L138","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Replay the snapshot recording from its beginning (position 0), not from a mid-stream position","Restore a complete snapshot recording from backup","Re-take a snapshot on the leader and use its recordingId","Check archive segments for deletion/trimming of early frames"],"exampleFix":"// before\narchive.startReplay(recordingId, midStreamPosition, ...)\n// after\narchive.startReplay(recordingId, 0L, ...); // replay the full snapshot from the start","handlingStrategy":"validation","validationCode":"// Ensure replay starts at recording position 0 and that the earliest archive segment still exists\nlong startPosition = 0L; // never a mid-stream position for snapshot replay","typeGuard":null,"tryCatchPattern":"try {\n    snapshotPlayer.load(recordingId, ...);\n} catch (ClusterException e) {\n    if (\"missing begin snapshot\".equals(e.getMessage())) {\n        // recording truncated at the start — use backup\n        restoreFromBackup();\n    } else { throw e; }\n}","preventionTips":["Configure archive retention so early segments of snapshot recordings are never purged","Replay snapshots only from position 0","Confirm the archive catalog start position is 0 before restore"],"tags":["aeron","cluster","snapshot","marker-order"],"backgroundTag":"invalid-state-transition","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}