{"record":{"id":"a5f0e866549f09e8","repo":"aeron-io/aeron","slug":"failed-to-instantiate-clusterclock-clockclassname","errorCode":null,"errorMessage":"failed to instantiate ClusterClock <clockClassName>","messagePattern":"failed to instantiate ClusterClock <clockClassName>","errorType":"exception","errorClass":"ClusterException","httpStatus":null,"severity":"error","filePath":"aeron-cluster/src/main/java/io/aeron/cluster/ConsensusModule.java","lineNumber":1800,"sourceCode":"\n            if (startupCanvassTimeoutNs / leaderHeartbeatTimeoutNs < 2)\n            {\n                throw new ClusterException(\n                    \"startupCanvassTimeoutNs=\" + startupCanvassTimeoutNs +\n                    \" must be a multiple of leaderHeartbeatTimeoutNs=\" + leaderHeartbeatTimeoutNs);\n            }\n\n            if (null == clusterClock)\n            {\n                final String clockClassName = System.getProperty(\n                    CLUSTER_CLOCK_PROP_NAME, MillisecondClusterClock.class.getName());\n                try\n                {\n                    clusterClock = (ClusterClock)Class.forName(clockClassName).getConstructor().newInstance();\n                }\n                catch (final Exception e)\n                {\n                    throw new ClusterException(\"failed to instantiate ClusterClock \" + clockClassName, e);\n                }\n            }\n\n            if (null == epochClock)\n            {\n                epochClock = SystemEpochClock.INSTANCE;\n            }\n\n            if (null == appVersionValidator)\n            {\n                appVersionValidator = AppVersionValidator.SEMANTIC_VERSIONING_VALIDATOR;\n            }\n\n            if (null == clusterTimeConsumerSupplier)\n            {\n                clusterTimeConsumerSupplier = (ctx) -> (timestamp) -> {};\n            }\n","sourceCodeStart":1782,"sourceCodeEnd":1818,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-cluster/src/main/java/io/aeron/cluster/ConsensusModule.java#L1782-L1818","documentation":"When no ClusterClock is set, conclude() instantiates one reflectively from the class named by the CLUSTER_CLOCK_PROP_NAME system property (default MillisecondClusterClock). If the class cannot be found, has no no-arg constructor, is not a ClusterClock, or its constructor throws, the exception is wrapped as a ClusterException \"failed to instantiate ClusterClock <className>\".","triggerScenarios":"Setting -Daeron.cluster.clock (ClusterClock class name property) to a missing class, an abstract class, a class without a public no-arg constructor, or a class not implementing ClusterClock.","commonSituations":"Typo in the class name or package; enabling a high-resolution clock (e.g. CachedEpochClock/offset-clock experiments) and using the wrong class; fat-jar shading removing the clock class; upgrading Aeron where the clock class was renamed/removed.","solutions":["Fix the system property to a fully-qualified ClusterClock implementation with a public no-arg constructor","Remove the property to fall back to MillisecondClusterClock","Call ctx.clusterClock(new MillisecondClusterClock()) (or your implementation) explicitly instead of relying on reflection"],"exampleFix":"// before\nSystem.setProperty(\"aeron.cluster.clock\", \"io.aeron.cluster.HighResClock\"); // class missing\n// after\nSystem.setProperty(\"aeron.cluster.clock\", \"io.aeron.cluster.HighResolutionClusterClock\");\n// or better: ctx.clusterClock(new HighResolutionClusterClock());","handlingStrategy":"try-catch","validationCode":"String name = System.getProperty(\"aeron.cluster.clock\");\nif (name != null) {\n    Class<?> c = Class.forName(name);\n    if (!ClusterClock.class.isAssignableFrom(c) || c.getConstructor().getModifiers() != Modifier.PUBLIC) {\n        throw new IllegalArgumentException(name + \" is not a public ClusterClock with a no-arg constructor\");\n    }\n}","typeGuard":null,"tryCatchPattern":"try { ctx.conclude(); } catch (ClusterException e) { if (e.getMessage().startsWith(\"failed to instantiate ClusterClock\")) { ctx.clusterClock(new MillisecondClusterClock()); } }","preventionTips":["Prefer ctx.clusterClock(new ...) over the reflection-based system property","Keep the clock class in the same artifact/classpath as the cluster","Test custom clocks with a plain new-instance check"],"tags":["reflection","configuration","classpath"],"backgroundTag":"class-not-found","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"}