aeron-io/aeron · error · InvalidChannelException

term-offset= out of range: channel=

Error message

term-offset={termOffset} out of range: channel={channelUri}

What it means

Raised while parsing publication channel URI parameters: when the complete set of initial-term-id, term-id and term-offset params is supplied, the term-offset value is checked against the log buffer limits. This exception fires when the given termOffset is negative or exceeds LogBufferDescriptor.TERM_MAX_LENGTH, because a term offset outside that range cannot address a position within a term log buffer. It rejects the channel configuration before the publication is created.

Solutions

Clamp term-offset to the range 0..TERM_MAX_LENGTH before building the URI
Remove the param entirely if the offset is unknown
Compute the offset from a position as position & (termLength - 1)

Example fix

// before
"aeron:udp?endpoint=...:40456|term-offset=2147483648"
// after
"aeron:udp?endpoint=...:40456|term-offset=1073741823"

Defensive patterns

Strategy: validation

Validate before calling

if (termOffset < 0 || termOffset > LogBufferDescriptor.TERM_MAX_LENGTH) throw new IllegalArgumentException("term-offset out of range");

Try / catch

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

Prevention

Never use -1 as a sentinel in URIs
Clamp computed offsets before embedding them in URIs
Validate size units (k/m/g) when generating URIs

When it happens

Trigger: A channel URI containing term-offset=-1 or term-offset greater than LogBufferDescriptor.TERM_MAX_LENGTH when adding a publication.

Common situations: Using -1 as a 'default' sentinel in the URI; misuniting sizes (e.g. passing bytes value larger than 1GB); generated URIs from buggy tooling.

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/2f1182c7eb3a6fc6. Report an issue: GitHub.

Appendix: source

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

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);
}

View on GitHub (pinned to 6d60124e15)