aeron-io/aeron · error · InvalidChannelException

term-offset= > term-length= : channel=

Error message

term-offset={termOffset} > term-length={termLength}: channel={channelUri}

What it means

When term-offset is supplied in the channel URI it must not exceed the publication's term-length, since an offset beyond the term buffer is meaningless. Aeron rejects the channel with InvalidChannelException.

Solutions

Reduce term-offset to be < term-length
Increase the term-length URI param (power of 2, within TERM_MAX_LENGTH) to exceed the offset
Remove the term-offset param to let Aeron manage positions

Example fix

// before
"aeron:udp?endpoint=...:40456|term-length=65536|term-offset=131072"
// after
"aeron:udp?endpoint=...:40456|term-length=262144|term-offset=131072"

Defensive patterns

Strategy: validation

Validate before calling

if (termOffset >= termLength) throw new IllegalArgumentException("term-offset must be < term-length");

Try / catch

try { pub = aeron.addPublication(uri, streamId); } catch (InvalidChannelException e) { log.error("invalid term params: {}", e.getMessage()); }

Prevention

Derive term-offset from position & (termLength - 1)
Keep term-length and term-offset configured together
Assert power-of-two term lengths and offsets within them

When it happens

Trigger: A channel URI with term-offset larger than the resolved term-length (e.g. term-offset=2097152 with default 64KB–1MB term length, or a term-length param smaller than the offset).

Common situations: Copying URIs between publications configured with different term-lengths; setting a large term-offset while leaving default (small) term-length; typos like term-offset=1M against a 64KB term buffer.

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

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

Appendix: source

Thrown at aeron-driver/src/main/java/io/aeron/driver/PublicationParams.java:128

        final String termOffsetStr = channelUri.get(TERM_OFFSET_PARAM_NAME);
        count = termOffsetStr != null ? count + 1 : count;

        if (count > 0)
        {
            if (count < 3)
            {
                throw new InvalidChannelException("params must be used as a complete set: " +
                    INITIAL_TERM_ID_PARAM_NAME + " " + TERM_ID_PARAM_NAME + " " + TERM_OFFSET_PARAM_NAME + " channel=" +
                    channelUri);
            }

            params.initialTermId = parseInt(initialTermIdStr, INITIAL_TERM_ID_PARAM_NAME);
            params.termId = parseInt(termIdStr, TERM_ID_PARAM_NAME);
            params.termOffset = parseInt(termOffsetStr, TERM_OFFSET_PARAM_NAME);

            if (params.termOffset > params.termLength)
            {
                throw new InvalidChannelException(
                    TERM_OFFSET_PARAM_NAME + "=" + params.termOffset + " > " +
                    TERM_LENGTH_PARAM_NAME + "=" + params.termLength + ": channel=" + channelUri);
            }

            if (params.termOffset < 0 || params.termOffset > LogBufferDescriptor.TERM_MAX_LENGTH)
            {
                throw new InvalidChannelException(
                    TERM_OFFSET_PARAM_NAME + "=" + params.termOffset + " out of range: channel=" + channelUri);
            }

            if (!FrameDescriptor.isFrameAligned(params.termOffset))
            {
                throw new InvalidChannelException(
                    TERM_OFFSET_PARAM_NAME + "=" + params.termOffset +
                    " must be a multiple of FRAME_ALIGNMENT: channel=" + channelUri);
            }

            if (params.termId - params.initialTermId < 0)

View on GitHub (pinned to 6d60124e15)