{"record":{"id":"fe589c0b60d64643","repo":"aeron-io/aeron","slug":"expected-schemaid-messageheaderdecoder-schema-id-actual-fe589c","errorCode":null,"errorMessage":"expected schemaId=${MessageHeaderDecoder.SCHEMA_ID}, actual=${schemaId}","messagePattern":"expected schemaId=(.+?), actual=(.+?)","errorType":"console","errorClass":"ClusterException","httpStatus":null,"severity":"error","filePath":"aeron-cluster/src/main/java/io/aeron/cluster/service/ServiceSnapshotLoader.java","lineNumber":79,"sourceCode":"\n    TimeUnit timeUnit()\n    {\n        return timeUnit;\n    }\n\n    int poll()\n    {\n        return image.controlledPoll(fragmentAssembler, FRAGMENT_LIMIT);\n    }\n\n    public Action onFragment(final DirectBuffer buffer, final int offset, final int length, final Header header)\n    {\n        messageHeaderDecoder.wrap(buffer, offset);\n\n        final int schemaId = messageHeaderDecoder.schemaId();\n        if (MessageHeaderDecoder.SCHEMA_ID != schemaId)\n        {\n            throw new ClusterException(\"expected schemaId=\" + MessageHeaderDecoder.SCHEMA_ID + \", actual=\" + schemaId);\n        }\n\n        switch (messageHeaderDecoder.templateId())\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())","sourceCodeStart":61,"sourceCodeEnd":97,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-cluster/src/main/java/io/aeron/cluster/service/ServiceSnapshotLoader.java#L61-L97","documentation":"ServiceSnapshotLoader.onFragment validates the SBE MessageHeader schemaId of every fragment received while loading a service snapshot from the archive. If the schemaId does not match the cluster protocol's MessageHeaderDecoder.SCHEMA_ID, the snapshot data is not in the expected schema and this ClusterException is thrown.","triggerScenarios":"Replaying a snapshot recording whose fragments were written with a different SBE schema id — snapshot produced by a different Aeron version, corrupted snapshot data, or unrelated data captured in the recording.","commonSituations":"Upgrading Aeron versions across a cluster while replaying old snapshots; restoring a snapshot from a different cluster/backup; archive replay misconfiguration pointing the loader at the wrong recording.","solutions":["Restore a snapshot taken with the same Aeron/protocol version as the running code.","Perform a supported upgrade path (replay with old version, take new snapshot) rather than replaying old snapshots on new code.","Verify the archive replay is bound to the correct recordingId for the service snapshot.","Check snapshot recording integrity; re-take the snapshot if data is corrupt."],"exampleFix":"// before\n// replaying snapshot from aeron 1.38 with aeron-cluster 1.44\n// after\n// upgrade cluster with old version, let it snapshot, then start new version on the new snapshot","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    snapshotLoader.onFragment(buffer, offset, length, header);\n} catch (ClusterException e) {\n    if (e.getMessage().contains(\"expected schemaId=\")) {\n        // snapshot schema mismatch: restore compatible snapshot or upgrade via re-snapshot\n    } else {\n        throw e;\n    }\n}","preventionTips":["Only replay snapshots produced by the same Aeron/protocol version.","Follow supported upgrade procedures (old version replays, new snapshot, then upgrade).","Validate recordingId targets the intended service snapshot before replay."],"tags":["aeron","sbe","snapshot","schema"],"backgroundTag":"schema-validation-failed","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"}