{"record":{"id":"d5263b73dbc8cc91","repo":"aeron-io/aeron","slug":"expected-schemaid-messageheaderdecoder-schema-id-actual-d5263b","errorCode":null,"errorMessage":"expected schemaId=<MessageHeaderDecoder.SCHEMA_ID>, actual=<schemaId>","messagePattern":"expected schemaId=<MessageHeaderDecoder\\.SCHEMA_ID>, actual=<schemaId>","errorType":"exception","errorClass":"ClusterException","httpStatus":null,"severity":"error","filePath":"aeron-cluster/src/main/java/io/aeron/cluster/client/EgressAdapter.java","lineNumber":121,"sourceCode":"        messageHeaderDecoder.wrap(buffer, offset);\n\n        final int templateId = messageHeaderDecoder.templateId();\n        final int schemaId = messageHeaderDecoder.schemaId();\n        if (schemaId != MessageHeaderDecoder.SCHEMA_ID)\n        {\n            if (listenerExtension != null)\n            {\n                listenerExtension.onExtensionMessage(\n                    messageHeaderDecoder.blockLength(),\n                    templateId,\n                    schemaId,\n                    messageHeaderDecoder.version(),\n                    buffer,\n                    offset + MessageHeaderDecoder.ENCODED_LENGTH,\n                    length - MessageHeaderDecoder.ENCODED_LENGTH);\n                return;\n            }\n            throw new ClusterException(\"expected schemaId=\" +\n                MessageHeaderDecoder.SCHEMA_ID + \", actual=\" + schemaId);\n        }\n\n        switch (templateId)\n        {\n            case SessionMessageHeaderDecoder.TEMPLATE_ID:\n            {\n                sessionMessageHeaderDecoder.wrap(\n                    buffer,\n                    offset + MessageHeaderDecoder.ENCODED_LENGTH,\n                    messageHeaderDecoder.blockLength(),\n                    messageHeaderDecoder.version());\n\n                final long sessionId = sessionMessageHeaderDecoder.clusterSessionId();\n                if (sessionId == clusterSessionId)\n                {\n                    listener.onMessage(\n                        sessionId,","sourceCodeStart":103,"sourceCodeEnd":139,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-cluster/src/main/java/io/aeron/cluster/client/EgressAdapter.java#L103-L139","documentation":"EgressAdapter.onFragment decoded the SBE MessageHeader of an egress fragment and found a schemaId that does not match the cluster egress schema (MessageHeaderDecoder.SCHEMA_ID). It throws ClusterException since decoding with the compiled codecs would be unsafe.","triggerScenarios":"Subscribing to a stream carrying a different SBE schema than aeron cluster egress; version mismatch between client and cluster SBE codecs.","commonSituations":"Mixed Aeron versions after upgrade; wrong subscription channel/stream wiring; custom protocols reusing the egress stream.","solutions":["Align aeron-cluster versions between client and cluster","Check that the subscription points at the correct egress streamId/channel","Regenerate codecs from the matching schema if customized","Inspect the unexpected schemaId to trace the actual producer of the fragment"],"exampleFix":"// before\nAeronCluster.connect(new AeronCluster.Context()); // cluster on different schema version\n// after\n// pin both sides to the same aeron-cluster release before reconnecting","handlingStrategy":"validation","validationCode":"MessageHeaderDecoder h = new MessageHeaderDecoder().wrap(buffer, offset);\nif (h.schemaId() != MessageHeaderDecoder.SCHEMA_ID) {\n    // handle mismatch before calling EgressAdapter.onFragment\n}","typeGuard":null,"tryCatchPattern":"try {\n    adapter.onFragment(buffer, offset, length, header);\n} catch (ClusterException ex) {\n    // log and skip incompatible fragment\n}","preventionTips":["Keep client and cluster SBE codecs from the same release","Validate subscription endpoints during integration tests","Track schemaId in diagnostics when upgrading"],"tags":["aeron","sbe","schema","cluster-client"],"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-15T23:17:13.987Z"}