aeron-io/aeron · error · ClusterException

either a instance or class name for the service must be…

Error message

either a instance or class name for the service must be provided

What it means

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.

Solutions

1. Pass -Daeron.cluster.service.class.name=com.example.MyService on launch
2. Call context.clusteredService(new MyService()) (or the class name setter) on the ClusteredServiceContainer.Context before concluding
3. Fix the property name/value if it was set but mistyped
4. Ensure the class has a public no-arg constructor and implements ClusteredService

Example fix

// before
ClusteredServiceContainer.launch(new ClusteredServiceContainer.Context());
// after
ClusteredServiceContainer.launch(
    new ClusteredServiceContainer.Context()
        .clusteredService(new MyClusteredService()));

String className = System.getProperty("aeron.cluster.service.class.name");
if (null == className && serviceInstance == null) {
    throw new IllegalArgumentException("set aeron.cluster.service.class.name or call context.clusteredService(...)");
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• not found in
• clusterMembers and endpoints differ
• service id outside allowed range
• Aeron client must use a RethrowingErrorHandler
• Aeron client instance must set…

AI-assisted analysis of aeron-io/aeron@6d60124e15 (2026-09-12). Data as JSON: /api/errors/ff30eeca954b52e0. Report an issue: GitHub.

Appendix: source

Thrown at aeron-cluster/src/main/java/io/aeron/cluster/service/ClusteredServiceContainer.java:682

         *
         * @return threshold value in nanoseconds.
         */
        public static long snapshotDurationThresholdNs()
        {
            return getDurationInNanos(SNAPSHOT_DURATION_THRESHOLD_PROP_NAME, SNAPSHOT_DURATION_THRESHOLD_DEFAULT_NS);
        }

        /**
         * Create a new {@link ClusteredService} based on the configured {@link #SERVICE_CLASS_NAME_PROP_NAME}.
         *
         * @return a new {@link ClusteredService} based on the configured {@link #SERVICE_CLASS_NAME_PROP_NAME}.
         */
        public static ClusteredService newClusteredService()
        {
            final String className = System.getProperty(Configuration.SERVICE_CLASS_NAME_PROP_NAME);
            if (null == className)
            {
                throw new ClusterException("either a instance or class name for the service must be provided");
            }

            try
            {
                return (ClusteredService)Class.forName(className).getConstructor().newInstance();
            }
            catch (final Exception ex)
            {
                LangUtil.rethrowUnchecked(ex);
                return null;
            }
        }

        /**
         * Create a new {@link DelegatingErrorHandler} defined by {@link #DELEGATING_ERROR_HANDLER_PROP_NAME}.
         *
         * @return a new {@link DelegatingErrorHandler} defined by {@link #DELEGATING_ERROR_HANDLER_PROP_NAME} or
         * null if property not set.

View on GitHub (pinned to 6d60124e15)