{"record":{"id":"0bece49ba2cc234c","repo":"aeron-io/aeron","slug":"expected-schemaid-messageheaderdecoder-schema-id-actual-0bece4","errorCode":null,"errorMessage":"expected schemaId=${MessageHeaderDecoder.SCHEMA_ID}, actual=${schemaId}","messagePattern":"expected schemaId=(.+?), actual=(.+?)","errorType":"exception","errorClass":"ClusterException","httpStatus":null,"severity":"error","filePath":"aeron-cluster/src/main/java/io/aeron/cluster/ClusterControlAdapter.java","lineNumber":82,"sourceCode":"    int poll()\n    {\n        return subscription.poll(fragmentAssembler, 1);\n    }\n\n    boolean isBound()\n    {\n        return subscription.isConnected();\n    }\n\n    @SuppressWarnings(\"MethodLength\")\n    private void 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 (schemaId != MessageHeaderDecoder.SCHEMA_ID)\n        {\n            throw new ClusterException(\"expected schemaId=\" + MessageHeaderDecoder.SCHEMA_ID + \", actual=\" + schemaId);\n        }\n\n        final int templateId = messageHeaderDecoder.templateId();\n        if (templateId == ClusterMembersResponseDecoder.TEMPLATE_ID)\n        {\n            clusterMembersResponseDecoder.wrap(\n                buffer,\n                offset + MessageHeaderDecoder.ENCODED_LENGTH,\n                messageHeaderDecoder.blockLength(),\n                messageHeaderDecoder.version());\n\n            final long correlationId = clusterMembersResponseDecoder.correlationId();\n            final int leaderMemberId = clusterMembersResponseDecoder.leaderMemberId();\n            final String activeMembers = clusterMembersResponseDecoder.activeMembers();\n            clusterMembersResponseDecoder.skipPassiveFollowers();\n\n            listener.onClusterMembersResponse(correlationId, leaderMemberId, activeMembers);\n        }","sourceCodeStart":64,"sourceCodeEnd":100,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-cluster/src/main/java/io/aeron/cluster/ClusterControlAdapter.java#L64-L100","documentation":"ClusterControlAdapter.onFragment wraps each incoming buffer with an SBE MessageHeaderDecoder and verifies the schemaId matches MessageHeaderDecoder.SCHEMA_ID. A mismatch means the fragment is not an Aeron cluster control SBE message of the expected schema, so decoding cannot proceed safely.","triggerScenarios":"A message arrives on the control-toggle/control-response subscription whose SBE schemaId differs from the cluster-codec schema (e.g. messages from a different schema version or unrelated publisher on the same channel).","commonSituations":"Mixed Aeron versions between cluster members (schema changed between releases), accidentally pointing multiple components at the same control channel, or garbage/corrupt frames on the channel.","solutions":["Ensure all cluster members and clients use the same Aeron version/schema","Stop unrelated publishers from sending on the control channel","Verify channel/endpoint configuration separates control traffic from other traffic","Regenerate/rebuild any custom codecs from the matching aeron-cluster schema"],"exampleFix":"// before\n// member on aeron 1.40 talking to member on 1.44 with changed schema\n// after\n// align versions:\n<dependency>\n  <groupId>io.aeron</groupId>\n  <artifactId>aeron-all</artifactId>\n  <version>1.44.1</version>\n</dependency>","handlingStrategy":"try-catch","validationCode":"// verify peer version compatibility before subscribing to control channel\n// keep aeron-all versions identical across all cluster nodes","typeGuard":null,"tryCatchPattern":"try {\n    controlAdapter.onFragment(buffer, offset, length, header);\n} catch (ClusterException e) {\n    if (e.getMessage().contains(\"expected schemaId\")) {\n        log.error(\"schema/version mismatch on control channel; check Aeron versions\", e);\n    }\n}","preventionTips":["Pin a single aeron-all version across the deployment","Never publish non-cluster SBE messages on control channels","Log the offending schemaId to identify the mismatching producer"],"tags":["aeron","sbe","schema","version-mismatch"],"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"}