aeron-io/aeron · error · ClusterException

service count of range [0, MAX_SERVICE_COUNT]: serviceCount

Error message

service count of range [0, MAX_SERVICE_COUNT]: serviceCount

What it means

During conclude(), the configured serviceCount is validated against the range [0, MAX_SERVICE_COUNT] (max 20 in Aeron Cluster). A negative or over-limit service count means the cluster cannot allocate per-service state, so conclude() throws a ClusterException immediately.

Solutions

1. Set serviceCount() to the actual number of clustered services, between 0 and 20
2. Check for arithmetic/parse bugs producing a negative count
3. Split the workload across multiple clusters if more than 20 services are needed

Example fix

// before
ctx.serviceCount(-1); // or 25
// after
ctx.serviceCount(3); // number of ClusteredServices in this node

int serviceCount = /* configured */;
if (serviceCount < 0 || serviceCount > ConsensusModule.Configuration.MAX_SERVICE_COUNT) {
    throw new IllegalArgumentException("serviceCount out of range: " + serviceCount);
}

try { ctx.conclude(); } catch (ClusterException e) { log.error("bad serviceCount", e); }

When it happens

Trigger: Setting ConsensusModule.Context.serviceCount() to a negative value or a value greater than MAX_SERVICE_COUNT (20) before conclude().

Common situations: Misreading serviceCount semantics (services per cluster vs. total cluster instances); computing the count dynamically and accidentally passing -1 or 0-padded garbage; copying config from a scaled deployment with more than 20 services.

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

• AeronArchive.Context.messageRetryAttempts must be > 0, got:
• AeronCluster.Context.clientName length must be <=…
• AeronCluster.Context ingressEndpoints must be null when…
• applicationSpecificFeedback length must be equal to
• clientLivenessTimeoutNs=

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

Appendix: source

Thrown at aeron-cluster/src/main/java/io/aeron/cluster/ConsensusModule.java:1736

            }
        }

        /**
         * 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();
            }

            validateLogChannel();

            if (serviceCount < 0 || serviceCount > MAX_SERVICE_COUNT)
            {
                throw new ClusterException("service count of range [0, " + MAX_SERVICE_COUNT + "]: " + serviceCount);
            }

            if (null == clusterDir)
            {
                clusterDir = new File(clusterDirectoryName);
            }

            if (null == markFileDir)
            {
                final String dir = ClusteredServiceContainer.Configuration.markFileDir();
                markFileDir = Strings.isEmpty(dir) ? clusterDir : new File(dir);
            }

            try
            {
                clusterDir = clusterDir.getCanonicalFile();
                clusterDirectoryName = clusterDir.getAbsolutePath();
                markFileDir = markFileDir.getCanonicalFile();

View on GitHub (pinned to 6d60124e15)