{"record":{"id":"3c0e0b7e62930ad0","repo":"aeron-io/aeron","slug":"expected-schemaid-schema-id-actual-schemaid","errorCode":null,"errorMessage":"expected schemaId=<SCHEMA_ID>, actual=<schemaId>","messagePattern":"expected schemaId=<SCHEMA_ID>, actual=<schemaId>","errorType":"exception","errorClass":"ClusterException","httpStatus":null,"severity":"critical","filePath":"aeron-cluster/src/main/java/io/aeron/cluster/ConsensusModuleAdapter.java","lineNumber":67,"sourceCode":"    {\n        subscription.close();\n    }\n\n    int poll()\n    {\n        return subscription.controlledPoll(fragmentAssembler, FRAGMENT_LIMIT);\n    }\n\n    @SuppressWarnings(\"MethodLength\")\n    private ControlledFragmentHandler.Action onFragment(\n        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 (schemaId != MessageHeaderDecoder.SCHEMA_ID)\n        {\n            throw new ClusterException(\"expected schemaId=\" + MessageHeaderDecoder.SCHEMA_ID + \", actual=\" + schemaId);\n        }\n\n        ControlledFragmentHandler.Action action = ControlledFragmentHandler.Action.CONTINUE;\n\n        switch (messageHeaderDecoder.templateId())\n        {\n            case SessionMessageHeaderDecoder.TEMPLATE_ID:\n                sessionMessageHeaderDecoder.wrap(\n                    buffer,\n                    offset + MessageHeaderDecoder.ENCODED_LENGTH,\n                    messageHeaderDecoder.blockLength(),\n                    messageHeaderDecoder.version());\n\n                consensusModuleAgent.onServiceMessage(\n                    sessionMessageHeaderDecoder.clusterSessionId(),\n                    buffer,\n                    offset + AeronCluster.SESSION_HEADER_LENGTH,\n                    length - AeronCluster.SESSION_HEADER_LENGTH);","sourceCodeStart":49,"sourceCodeEnd":85,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-cluster/src/main/java/io/aeron/cluster/ConsensusModuleAdapter.java#L49-L85","documentation":"ConsensusModuleAdapter.onFragment validates that the SBE message header of every incoming fragment carries the expected schema id (MessageHeaderDecoder.SCHEMA_ID). A mismatch means the sender encoded messages with a different SBE schema, so decoding would produce garbage. The library throws immediately to fail fast rather than misinterpret cluster protocol messages.","triggerScenarios":"A fragment is polled on the consensus module subscription whose messageHeaderDecoder.schemaId() does not equal MessageHeaderDecoder.SCHEMA_ID, i.e. the remote peer (or a mixed-version node) sends cluster protocol messages encoded with a different aeron-cluster SBE schema.","commonSituations":"Cluster nodes running mismatched Aeron versions with regenerated SBE codecs; a custom service or rogue client publishing non-cluster messages onto the consensus module's subscription channel; stale build artifacts mixing codec jars.","solutions":["Run the same Aeron version on every cluster node so all nodes share identical SBE schema ids.","Verify nothing else (services, tests, probes) is publishing onto the cluster/consensus module transport channel.","Rebuild cleanly to eliminate stale or conflicting aeron-cluster codec jars on the classpath.","Check message archives/logs replayed into the cluster were produced with the same schema version."],"exampleFix":"// before: cluster mixes node versions\n-Daeron.cluster.dir=... // node on aeron 1.40, others on 1.44\n// after: align versions\nevery node uses identical aeron artifacts, cluster restarts cleanly","handlingStrategy":"validation","validationCode":"// before joining the cluster, assert codec schema consistency\nif (MessageHeaderDecoder.SCHEMA_ID != expectedClusterSchemaId) {\n    throw new IllegalStateException(\"codec schema id mismatch: rebuild against the cluster's SBE schema\");\n}","typeGuard":null,"tryCatchPattern":"try { agent.doWork(); } catch (ClusterException e) { if (e.getMessage().contains(\"expected schemaId\")) { haltAndRejoinWithMatchingVersion(); } else { throw e; } }","preventionTips":["Pin identical Aeron versions across all cluster nodes.","Never publish application messages on cluster protocol channels.","Rebuild from clean artifacts when upgrading codecs."],"tags":["sbe","schema-mismatch","cluster","protocol"],"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"}