{"record":{"id":"ff30eeca954b52e0","repo":"aeron-io/aeron","slug":"either-a-instance-or-class-name-for-the-service-must-be","errorCode":null,"errorMessage":"either a instance or class name for the service must be provided","messagePattern":"either a instance or class name for the service must be provided","errorType":"validation","errorClass":"ClusterException","httpStatus":null,"severity":"error","filePath":"aeron-cluster/src/main/java/io/aeron/cluster/service/ClusteredServiceContainer.java","lineNumber":682,"sourceCode":"         *\n         * @return threshold value in nanoseconds.\n         */\n        public static long snapshotDurationThresholdNs()\n        {\n            return getDurationInNanos(SNAPSHOT_DURATION_THRESHOLD_PROP_NAME, SNAPSHOT_DURATION_THRESHOLD_DEFAULT_NS);\n        }\n\n        /**\n         * Create a new {@link ClusteredService} based on the configured {@link #SERVICE_CLASS_NAME_PROP_NAME}.\n         *\n         * @return a new {@link ClusteredService} based on the configured {@link #SERVICE_CLASS_NAME_PROP_NAME}.\n         */\n        public static ClusteredService newClusteredService()\n        {\n            final String className = System.getProperty(Configuration.SERVICE_CLASS_NAME_PROP_NAME);\n            if (null == className)\n            {\n                throw new ClusterException(\"either a instance or class name for the service must be provided\");\n            }\n\n            try\n            {\n                return (ClusteredService)Class.forName(className).getConstructor().newInstance();\n            }\n            catch (final Exception ex)\n            {\n                LangUtil.rethrowUnchecked(ex);\n                return null;\n            }\n        }\n\n        /**\n         * Create a new {@link DelegatingErrorHandler} defined by {@link #DELEGATING_ERROR_HANDLER_PROP_NAME}.\n         *\n         * @return a new {@link DelegatingErrorHandler} defined by {@link #DELEGATING_ERROR_HANDLER_PROP_NAME} or\n         * null if property not set.","sourceCodeStart":664,"sourceCodeEnd":700,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-cluster/src/main/java/io/aeron/cluster/service/ClusteredServiceContainer.java#L664-L700","documentation":"Thrown as ClusterException by ClusteredServiceContainer.ClusteredServiceContainer.Main-style static newClusteredService() when no service instance was set and the system property aeron.cluster.service.class.name is not defined, so the container cannot instantiate the clustered service. The static factory relies solely on the system property to build the service reflectively.","triggerScenarios":"Launching ClusteredServiceContainer without calling Context.clusteredService(...) and without setting -Daeron.cluster.service.class.name=...; using newClusteredService() in code that never set the property; property name typo so it is not found.","commonSituations":"Running the container from the command line/agent harness without the class name property; embedding the container but forgetting to register a service instance; renaming the service class without updating the launch script.","solutions":["Pass -Daeron.cluster.service.class.name=com.example.MyService on launch","Call context.clusteredService(new MyService()) (or the class name setter) on the ClusteredServiceContainer.Context before concluding","Fix the property name/value if it was set but mistyped","Ensure the class has a public no-arg constructor and implements ClusteredService"],"exampleFix":"// before\nClusteredServiceContainer.launch(new ClusteredServiceContainer.Context());\n// after\nClusteredServiceContainer.launch(\n    new ClusteredServiceContainer.Context()\n        .clusteredService(new MyClusteredService()));","handlingStrategy":"validation","validationCode":"String className = System.getProperty(\"aeron.cluster.service.class.name\");\nif (null == className && serviceInstance == null) {\n    throw new IllegalArgumentException(\"set aeron.cluster.service.class.name or call context.clusteredService(...)\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always register the service instance programmatically when embedding the container","Keep launch scripts in sync with the service class name","Verify the property before launching with the static factory"],"tags":["aeron","cluster","configuration","service"],"backgroundTag":"missing-required-config-field","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"}