aeron-io/aeron · error · ConfigurationException

logChannel must not contain

Error message

logChannel must not contain: <termOffset param name>

What it means

Final branch of validateLogChannel(): the logChannel URI must not contain termOffset, as cluster consensus must control the offset within the log term. A ConfigurationException naming the parameter is thrown.

Solutions

1. Remove termOffset from the logChannel URI.
2. For log recovery, rely on the cluster's replay mechanism rather than pinning channel params.
3. Restrict the logChannel to transport parameters only.

Example fix

// before
ctx.logChannel("aeron:udp?endpoint=localhost:20000|termOffset=0");
// after
ctx.logChannel("aeron:udp?endpoint=localhost:20000");

ChannelUri uri = ChannelUri.parse(logChannel);
if (uri.containsKey("termOffset")) {
    throw new IllegalArgumentException("logChannel must not contain termOffset");
}

When it happens

Trigger: logChannel URI includes termOffset, e.g. 'aeron:udp?endpoint=...|termOffset=0'.

Common situations: Channel string reused from a replay/recording publication configuration; attempts to resume a log at a specific offset by pinning termOffset.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• logChannel must not contain
• logChannel must not contain
• Channel media type mismatch. When using…
• ClusterBackup.Context.catchupEndpoint must be set
• difference greater than 2^31 - 1: termId=

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

Appendix: source

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

            }

            throw new ClusterException("invalid TimerServiceSupplier: " + timeServiceClassName);
        }

        private void validateLogChannel()
        {
            final ChannelUri logChannelUri = parse(logChannel);
            if (logChannelUri.containsKey(INITIAL_TERM_ID_PARAM_NAME))
            {
                throw new ConfigurationException("logChannel must not contain: " + INITIAL_TERM_ID_PARAM_NAME);
            }
            if (logChannelUri.containsKey(TERM_ID_PARAM_NAME))
            {
                throw new ConfigurationException("logChannel must not contain: " + TERM_ID_PARAM_NAME);
            }
            if (logChannelUri.containsKey(TERM_OFFSET_PARAM_NAME))
            {
                throw new ConfigurationException("logChannel must not contain: " + TERM_OFFSET_PARAM_NAME);
            }
        }

        /**
         * {@inheritDoc}
         */
        @Override
        public String toString()
        {
            return "ConsensusModule.Context" +
                "\n{" +
                "\n    isConcluded=" + isConcluded() +
                "\n    ownsAeronClient=" + ownsAeronClient +
                "\n    aeronDirectoryName='" + aeronDirectoryName + '\'' +
                "\n    aeron=" + aeron +
                "\n    deleteDirOnStart=" + deleteDirOnStart +
                "\n    clusterDirectoryName='" + clusterDirectoryName + '\'' +
                "\n    clusterDir=" + clusterDir +

View on GitHub (pinned to 6d60124e15)