{"record":{"id":"9abf109c741051c1","repo":"aeron-io/aeron","slug":"incompatible-version-appversion-snapshot-snapshotappversion","errorCode":null,"errorMessage":"incompatible version: <appVersion> snapshot=<snapshotAppVersion>","messagePattern":"incompatible version: <appVersion> snapshot=<snapshotAppVersion>","errorType":"exception","errorClass":"ClusterException","httpStatus":null,"severity":"critical","filePath":"aeron-cluster/src/main/java/io/aeron/cluster/ConsensusModuleAgent.java","lineNumber":637,"sourceCode":"     * {@inheritDoc}\n     */\n    @Override\n    public int clusterId()\n    {\n        return ctx.clusterId();\n    }\n\n    public ClusterMember clusterMember()\n    {\n        return thisMember;\n    }\n\n    public void onLoadBeginSnapshot(\n        final int appVersion, final TimeUnit timeUnit, final DirectBuffer buffer, final int offset, final int length)\n    {\n        if (!ctx.appVersionValidator().isVersionCompatible(ctx.appVersion(), appVersion))\n        {\n            throw new ClusterException(\n                \"incompatible version: \" + SemanticVersion.toString(ctx.appVersion()) +\n                \" snapshot=\" + SemanticVersion.toString(appVersion),\n                AeronException.Category.FATAL);\n        }\n\n        if (timeUnit != clusterTimeUnit)\n        {\n            throw new ClusterException(\n                \"incompatible time unit: \" + clusterTimeUnit + \" snapshot=\" + timeUnit, AeronException.Category.FATAL);\n        }\n    }\n\n    public ControlledFragmentHandler.Action onExtensionMessage(\n        final int actingBlockLength,\n        final int templateId,\n        final int schemaId,\n        final int actingVersion,\n        final DirectBuffer buffer,","sourceCodeStart":619,"sourceCodeEnd":655,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-cluster/src/main/java/io/aeron/cluster/ConsensusModuleAgent.java#L619-L655","documentation":"When loading a snapshot the consensus module compares the application version recorded in the snapshot against the configured app version using ctx.appVersionValidator(). If they are incompatible it throws a FATAL ClusterException because replaying a snapshot made by incompatible service code would corrupt state.","triggerScenarios":"onLoadBeginSnapshot receives an appVersion from the snapshot header that fails ClusterVersionValidator/isVersionCompatible against the currently configured ctx.appVersion(), e.g. starting a cluster on a newer (or older) major application version with an old snapshot.","commonSituations":"Upgrading cluster services without taking a fresh snapshot; rolling back an upgrade with a snapshot written by newer code; misconfigured appVersion in the consensus module context.","solutions":["Take a fresh snapshot with the old version, then upgrade and start the new version from that snapshot.","Configure the app version validator / semanticVersionCheck to permit the version transition you intend.","Restore a snapshot matching the currently running application version.","If intentional, adjust ctx.appVersion() so it is compatible with the snapshot's recorded version."],"exampleFix":"// before: appVersion bumped 1.2 -> 2.0, old snapshot replayed\n// after: snapshot on old version first\ncurl cluster/snapshot  # while still on 1.2, then deploy 2.0","handlingStrategy":"validation","validationCode":"// before loading\nint snapshotVersion = readSnapshotAppVersion(clusterDir);\nif (!ctx.appVersionValidator().isVersionCompatible(ctx.appVersion(), snapshotVersion)) {\n    throw new IllegalStateException(\"snapshot appVersion \" + SemanticVersion.toString(snapshotVersion) + \" incompatible\");\n}","typeGuard":null,"tryCatchPattern":"try { cluster.start(); } catch (ClusterException e) { if (e.getMessage().startsWith(\"incompatible version\")) { restoreCompatibleSnapshot(); } else { throw e; } }","preventionTips":["Always take a snapshot before upgrading application versions.","Never roll back past a snapshot written by a newer version.","Test version upgrade/downgrade paths in staging."],"tags":["snapshot","version-compatibility","upgrade","cluster"],"backgroundTag":"incompatible-source-type","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"}