{"record":{"id":"976ecd19216e6726","repo":"aeron-io/aeron","slug":"incompatible-time-unit-clustertimeunit-snapshot","errorCode":null,"errorMessage":"incompatible time unit: <clusterTimeUnit> snapshot=<snapshotTimeUnit>","messagePattern":"incompatible time unit: <clusterTimeUnit> snapshot=<snapshotTimeUnit>","errorType":"exception","errorClass":"ClusterException","httpStatus":null,"severity":"critical","filePath":"aeron-cluster/src/main/java/io/aeron/cluster/ConsensusModuleAgent.java","lineNumber":645,"sourceCode":"    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,\n        final int offset,\n        final int length,\n        final Header header)\n    {\n        if (null != consensusModuleExtension)\n        {\n            return consensusModuleExtension.onIngressExtensionMessage(\n                actingBlockLength, templateId, schemaId, actingVersion, buffer, offset, length, header);","sourceCodeStart":627,"sourceCodeEnd":663,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-cluster/src/main/java/io/aeron/cluster/ConsensusModuleAgent.java#L627-L663","documentation":"During snapshot load the consensus module checks that the snapshot's recorded cluster time unit matches the clusterTimeUnit the node is configured with. A mismatch is FATAL because timer and timestamp semantics would be silently wrong if the snapshot were loaded with a different time unit.","triggerScenarios":"onLoadBeginSnapshot receives a TimeUnit that is not equal to the configured clusterTimeUnit, e.g. loading a snapshot taken by a cluster configured for MILLIS into a node configured for NANOS.","commonSituations":"Changing the cluster time unit configuration while keeping old snapshots; copying snapshot/marker data between clusters with different time unit settings; misconfigured ctx clusterTimeUnit on a new node.","solutions":["Align the node's clusterTimeUnit configuration with the time unit used by the snapshot.","Take a new snapshot from a cluster running with the desired time unit before switching.","Do not reuse snapshot directories across clusters that use different time units.","Verify aeron.cluster.credentials / context time unit settings are identical on all nodes."],"exampleFix":"// before\nctx.clusterTimeUnit(TimeUnit.NANOS); // snapshot was MILLIS\n// after\nctx.clusterTimeUnit(TimeUnit.MILLISECONDS); // matches snapshot","handlingStrategy":"validation","validationCode":"// before load\nif (configuredClusterTimeUnit != snapshotTimeUnit) {\n    throw new IllegalStateException(\"cluster time unit mismatch with snapshot: \" + snapshotTimeUnit);\n}","typeGuard":null,"tryCatchPattern":"try { cluster.start(); } catch (ClusterException e) { if (e.getMessage().startsWith(\"incompatible time unit\")) { reconfigureTimeUnitOrRestoreSnapshot(); } else { throw e; } }","preventionTips":["Keep clusterTimeUnit identical across the cluster's whole history of snapshots.","Document the time unit as immutable cluster configuration.","Never copy snapshot directories between differently configured clusters."],"tags":["snapshot","time-unit","configuration","cluster"],"backgroundTag":"incompatible-config-options","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"}