aeron-io/aeron · error · ClusterException

service count must be zero when ConsensusModuleExtension is…

Error message

service count must be zero when ConsensusModuleExtension is enabled

What it means

ConsensusModuleExtension is an alternative mode where the module itself provides the clustered service logic; it is incompatible with separately configured services. conclude() throws if a consensusModuleExtension was instantiated while serviceCount != 0.

Solutions

Remove the consensus module extension configuration property so the extension is not loaded.
Or set serviceCount to 0 (do not register ClusteredServiceContainer instances) if you intend to run the extension.
Search the launch environment/properties for whatever enables newConsensusModuleExtension and remove it.

Example fix

// before
System.setProperty("aeron.cluster.consensus.module.extension", "com.acme.MyExtension");
containerContext.serviceCount(2);
// after
// extension mode: no services
containerContext.serviceCount(0);
// or service mode: unset the extension property

Defensive patterns

Strategy: validation

Validate before calling

boolean extensionEnabled = null != Configuration.newConsensusModuleExtension();
if (extensionEnabled && ctx.serviceCount() != 0) {
    throw new IllegalArgumentException("unset the extension property or set serviceCount=0");
}

Prevention

Pick one mode: extension OR clustered services, never both
Grep deployment properties for extension flags
Isolate System properties per test to avoid leaks

When it happens

Trigger: Configuration resolves a non-null ConsensusModuleExtension (Configuration.newConsensusModuleExtension() / property) while serviceCount is nonzero — e.g. the extension property is set in the environment while the app also registers clustered services.

Common situations: Leftover aeron.cluster.extension system property from another deployment; container configuration combining service JARs with an extension build; test fixtures leaking properties via System.setProperty.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

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

Appendix: source

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

                logPublisher = new LogPublisher(logChannel());
            }

            if (null == egressPublisher)
            {
                egressPublisher = new EgressPublisher(leaderHeartbeatTimeoutNs);
            }

            final ChannelUri channelUri = parse(logChannel());
            isLogMdc = channelUri.isUdp() && null == channelUri.get(ENDPOINT_PARAM_NAME);

            if (null == consensusModuleExtension)
            {
                consensusModuleExtension = Configuration.newConsensusModuleExtension();
            }

            if (null != consensusModuleExtension && 0 != serviceCount)
            {
                throw new ClusterException("service count must be zero when ConsensusModuleExtension is enabled");
            }
            else if (null == consensusModuleExtension && 0 == serviceCount)
            {
                throw new ClusterException("zero services are only supported when ConsensusModuleExtension is enabled");
            }

            concludeMarkFile();

            if (CommonContext.shouldPrintConfigurationOnStart())
            {
                System.out.println(this);
            }
        }

        /**
         * Has the context had the {@link #conclude()} method called.
         *
         * @return true of the {@link #conclude()} method has been called.

View on GitHub (pinned to 6d60124e15)