{"record":{"id":"269bee7687a4be41","repo":"aeron-io/aeron","slug":"unexpected-snapshot-type-typeid","errorCode":null,"errorMessage":"unexpected snapshot type: ${typeId}","messagePattern":"unexpected snapshot type: (.+?)","errorType":"exception","errorClass":"ClusterException","httpStatus":null,"severity":"error","filePath":"aeron-cluster/src/main/java/io/aeron/cluster/ConsensusModuleSnapshotAdapter.java","lineNumber":97,"sourceCode":"                    buffer,\n                    offset + MessageHeaderDecoder.ENCODED_LENGTH,\n                    messageHeaderDecoder.blockLength(),\n                    messageHeaderDecoder.version());\n\n                listener.onLoadPendingMessage(sessionMessageHeaderDecoder.clusterSessionId(), buffer, offset, length);\n                break;\n\n            case SnapshotMarkerDecoder.TEMPLATE_ID:\n                snapshotMarkerDecoder.wrap(\n                    buffer,\n                    offset + MessageHeaderDecoder.ENCODED_LENGTH,\n                    messageHeaderDecoder.blockLength(),\n                    messageHeaderDecoder.version());\n\n                final long typeId = snapshotMarkerDecoder.typeId();\n                if (SNAPSHOT_TYPE_ID != typeId)\n                {\n                    throw new ClusterException(\"unexpected snapshot type: \" + typeId);\n                }\n\n                switch (snapshotMarkerDecoder.mark())\n                {\n                    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;","sourceCodeStart":79,"sourceCodeEnd":115,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-cluster/src/main/java/io/aeron/cluster/ConsensusModuleSnapshotAdapter.java#L79-L115","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the snapshotRecordingId in cluster mark file points to a genuine consensus-module snapshot recording","Restore from a known-good snapshot taken by the same cluster version","Check the archive catalog to confirm the recording type before replaying","Do not manually substitute recordings for snapshots"],"exampleFix":"// before\nClusterException: unexpected snapshot type: 1001\n// after: point to the correct snapshot recording id or take a fresh snapshot\nclient.takeSnapshot(); // then restart from the new snapshotRecordingId","handlingStrategy":"validation","validationCode":"// Before replay, confirm the recording is a consensus-module snapshot\n// check the recording's catalog entry / typeId metadata equals SNAPSHOT_TYPE_ID before pointing snapshotRecordingId at it","typeGuard":null,"tryCatchPattern":"try {\n    snapshotPlayer.load(recordingId, ...);\n} catch (ClusterException e) {\n    if (e.getMessage().startsWith(\"unexpected snapshot type\")) {\n        // fall back to a verified snapshot recording\n        loadVerifiedSnapshot();\n    } else { throw e; }\n}","preventionTips":["Never point snapshotRecordingId at arbitrary recordings","Record the snapshot recording id only via the cluster's own takeSnapshot flow","Validate recordings with aeron-archive tooling before restore"],"tags":["aeron","cluster","snapshot","snapshot-type"],"backgroundTag":"unexpected-response-shape","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"}