{"record":{"id":"c6083e0be421ef28","repo":"aeron-io/aeron","slug":"mark-file-major-version-version-does-not-match-software","errorCode":null,"errorMessage":"mark file major version ${version} does not match software: ${majorVersion}","messagePattern":"mark file major version (.+?) does not match software: (.+?)","errorType":"exception","errorClass":"ClusterException","httpStatus":null,"severity":"critical","filePath":"aeron-cluster/src/main/java/io/aeron/cluster/NodeStateFile.java","lineNumber":178,"sourceCode":"        {\n            throw new IllegalStateException(\n                \"offset=\" + offset + \" is not correctly aligned, it is not divisible by \" + ALIGNMENT);\n        }\n    }\n\n    private static void loadInitialState(\n        final MutableDirectBuffer buffer,\n        final NodeStateHeaderDecoder nodeStateHeaderDecoder,\n        final CandidateTermDecoder candidateTermDecoder,\n        final MessageHeaderDecoder messageHeaderDecoder)\n    {\n        nodeStateHeaderDecoder.wrap(\n            buffer, 0, NodeStateHeaderDecoder.BLOCK_LENGTH, NodeStateHeaderDecoder.SCHEMA_VERSION);\n\n        final int version = nodeStateHeaderDecoder.version();\n        if (ClusterMarkFile.MAJOR_VERSION != SemanticVersion.major(version))\n        {\n            throw new ClusterException(\n                \"mark file major version \" + SemanticVersion.major(version) +\n                \" does not match software: \" + ClusterMarkFile.MAJOR_VERSION);\n        }\n\n        final int footerOffset = scanForMessageTypeOffset(\n            nodeStateHeaderDecoder.sbeBlockLength(),\n            NodeStateFooterDecoder.TEMPLATE_ID,\n            buffer,\n            messageHeaderDecoder);\n\n        if (Aeron.NULL_VALUE == footerOffset)\n        {\n            throw new IllegalStateException(\"failed to find NodeStateFooter entry, file corrupt?\");\n        }\n\n        final int candidateTermOffset = scanForMessageTypeOffset(\n            nodeStateHeaderDecoder.sbeBlockLength(),\n            CandidateTermDecoder.TEMPLATE_ID,","sourceCodeStart":160,"sourceCodeEnd":196,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-cluster/src/main/java/io/aeron/cluster/NodeStateFile.java#L160-L196","documentation":"NodeStateFile.loadInitialState validates the SBE-encoded header of the node-state file: its major version must match ClusterMarkFile.MAJOR_VERSION of the installed Aeron software. A file written by an incompatible Aeron version is rejected with this ClusterException.","triggerScenarios":"Opening a node-state file created by a different Aeron major version (upgrade or downgrade of the Aeron driver/cluster across incompatible versions), or a file whose header version field is corrupted.","commonSituations":"Rolling upgrades where the cluster dir is reused across a major version jump; copying cluster state files between environments with different Aeron versions; corrupted file from a partial write/crash.","solutions":["Use the Aeron version that matches the file's major version to read/migrate the state","Delete (after backup) the node-state file and let the new version recreate it via createNew=true","Migrate state by reading the file with the old version and re-writing it with the new version","If the file was corrupted (version field nonsense), restore from backup"],"exampleFix":"// before: reusing old cluster dir after major upgrade\nNodeStateFile f = new NodeStateFile(clusterDir, false);\n// after: recreate the file under the new major version\nnew File(clusterDir, NodeStateFile.FILENAME).delete();\nNodeStateFile f = new NodeStateFile(clusterDir, true);","handlingStrategy":"validation","validationCode":"int version = readHeaderVersion(buffer); if (SemanticVersion.major(version) != ClusterMarkFile.MAJOR_VERSION) { /* migrate or recreate */ }","typeGuard":null,"tryCatchPattern":"try { f = new NodeStateFile(clusterDir, false); } catch (ClusterException e) { /* recreate file with matching version */ }","preventionTips":["Don't reuse cluster dirs across major Aeron upgrades without migration","Pin the same Aeron version across environments","Back up state files before upgrading"],"tags":["aeron-cluster","version-mismatch","sbe","node-state"],"backgroundTag":"version-mismatch","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-19T12:17:13.211Z"}