aeron-io/aeron · error · ConfigurationException

service id outside allowed range

Error message

service id outside allowed range [0,${maxId}]: ${serviceId}

What it means

Thrown as ConfigurationException when Context.serviceId(int) is set to a value outside the allowed range [0, MAX_SERVICE_COUNT - 1]. Each service container in a cluster must have a unique service id within this fixed maximum so slots in the service array and counters can be allocated.

Solutions

1. Set serviceId within [0, MAX_SERVICE_COUNT-1] (e.g. 0-based indexing for each container)
2. Fix the id source (config file/env parse) to produce a valid non-negative int
3. Check the MAX_SERVICE_COUNT constant for your Aeron version and keep the service count within it
4. Validate the id at startup before constructing the context

Example fix

// before
context.serviceId(Integer.parseInt(config.serviceId)); // config uses 1,2,3...
// after
int id = Integer.parseInt(config.serviceId) - 1;
if (id < 0 || id >= MAX_SERVICE_COUNT) throw new IllegalArgumentException("bad serviceId");
context.serviceId(id);

int maxId = MAX_SERVICE_COUNT - 1;
if (serviceId < 0 || serviceId > maxId) {
    throw new IllegalArgumentException("serviceId " + serviceId + " outside [0," + maxId + "]");
}
context.serviceId(serviceId);

When it happens

Trigger: Calling context.serviceId(n) with n < 0 or n >= MAX_SERVICE_COUNT during Context.conclude(); computing the service id from configuration/env with an off-by-one or unparsed string; launching more service containers than the max count with sequential ids.

Common situations: Starting several containers in one JVM and generating ids incorrectly; external config supplying 1-based ids while Aeron expects 0-based; configuration file listing more services than supported.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• not found in
• clusterMembers and endpoints differ
• either a instance or class name for the service must be…
• Aeron client must use a RethrowingErrorHandler
• invalid serviceId for count of

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

Appendix: source

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

                throw new RuntimeException(ex);
            }
        }

        /**
         * Conclude configuration by setting up defaults when specifics are not provided.
         */
        @SuppressWarnings("MethodLength")
        public void conclude()
        {
            if ((boolean)IS_CONCLUDED_VH.getAndSet(this, true))
            {
                throw new ConcurrentConcludeException();
            }

            final int maxId = MAX_SERVICE_COUNT - 1;
            if (serviceId < 0 || serviceId > maxId)
            {
                throw new ConfigurationException("service id outside allowed range [0," + maxId + "]: " + serviceId);
            }

            if (null == threadFactory)
            {
                threadFactory = Thread::new;
            }

            if (null == idleStrategySupplier)
            {
                idleStrategySupplier = Configuration.idleStrategySupplier(null);
            }

            if (null == appVersionValidator)
            {
                appVersionValidator = AppVersionValidator.SEMANTIC_VERSIONING_VALIDATOR;
            }

            if (null == epochClock)

View on GitHub (pinned to 6d60124e15)