{"record":{"id":"fdba01936816d738","repo":"aeron-io/aeron","slug":"expected-cluster-egress-schemaid-messageheaderdecoder-schema","errorCode":null,"errorMessage":"expected cluster egress schemaId=<MessageHeaderDecoder.SCHEMA_ID> actual=<schemaId>","messagePattern":"expected cluster egress schemaId=<MessageHeaderDecoder\\.SCHEMA_ID> actual=<schemaId>","errorType":"exception","errorClass":"ClusterException","httpStatus":null,"severity":"error","filePath":"aeron-cluster/src/main/java/io/aeron/cluster/client/AeronCluster.java","lineNumber":865,"sourceCode":"        final int schemaId = messageHeaderDecoder.schemaId();\n        final int templateId = messageHeaderDecoder.templateId();\n\n        if (schemaId != MessageHeaderDecoder.SCHEMA_ID)\n        {\n            if (egressListenerExtension != null)\n            {\n                egressListenerExtension.onExtensionMessage(\n                    messageHeaderDecoder.blockLength(),\n                    templateId,\n                    schemaId,\n                    messageHeaderDecoder.version(),\n                    buffer,\n                    offset + MessageHeaderDecoder.ENCODED_LENGTH,\n                    length - MessageHeaderDecoder.ENCODED_LENGTH);\n            }\n            else\n            {\n                throw new ClusterException(\n                    \"expected cluster egress schemaId=\" + MessageHeaderDecoder.SCHEMA_ID + \" actual=\" + schemaId);\n            }\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                    egressListener.onMessage(","sourceCodeStart":847,"sourceCodeEnd":883,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-cluster/src/main/java/io/aeron/cluster/client/AeronCluster.java#L847-L883","documentation":"onFragment decodes each egress fragment's SBE MessageHeader and validates that schemaId equals MessageHeaderDecoder.SCHEMA_ID for the cluster egress schema. A different schemaId means the fragment is not cluster egress data of the expected schema, so the library throws ClusterException rather than misinterpreting the buffer.","triggerScenarios":"Polling the client's egress subscription (onFragment) with an image whose data was produced against a different SBE schema version — e.g. a cluster running a different Aeron/SBE schema than the client library, or the subscription receiving unrelated traffic on the same channel/stream.","commonSituations":"Client and server Aeron versions mismatched after an upgrade; egress stream shared with other applications publishing non-egress messages; binary-stale deployments where one side was not restarted.","solutions":["Ensure client and cluster run Aeron versions with the same cluster egress SBE schema id; upgrade/restart both sides together.","Verify the egress Subscription channel/streamId is dedicated to cluster egress and not shared with other publishers.","Check for stale processes on the egress endpoint publishing old-schema messages.","Catch ClusterException in egress handlers and log schemaId to identify the offending publisher."],"exampleFix":"// before\nfinal int schemaId = headerDecoder.schemaId(); // throws later if unexpected\n// after\nif (headerDecoder.schemaId() != MessageHeaderDecoder.SCHEMA_ID) { logMismatchAndDropFragment(headerDecoder.schemaId()); return; }","handlingStrategy":"validation","validationCode":"if (messageHeaderDecoder.schemaId() != MessageHeaderDecoder.SCHEMA_ID) { log.error(\"unexpected egress schemaId \" + messageHeaderDecoder.schemaId()); return; }","typeGuard":null,"tryCatchPattern":"try { egressSubscription.poll(client::onFragment, 1); } catch (ClusterException e) { if (e.getMessage().contains(\"expected cluster egress schemaId\")) { haltAndCheckVersionMismatch(); } }","preventionTips":["Deploy client and cluster with matching Aeron/SBE schema versions.","Dedicate the egress channel/streamId to the cluster only.","Log and inspect schemaId on any non-conforming egress traffic."],"tags":["cluster","sbe","schema-mismatch","egress"],"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"}