aeron-io/aeron · error · IllegalArgumentException

term offset not in range 0-1g

Error message

term offset not in range 0-1g: ${termOffset}

What it means

ChannelUriStringBuilder.termOffset(Integer) rejects offsets outside the valid range 0..TERM_MAX_LENGTH (0 to 1GB). A term offset is a position inside a term buffer, so negative values or values beyond the term length are meaningless. The error is thrown before the value is stored on the builder.

Solutions

1. Ensure the offset is in 0..termLength range; mask a raw position: (int)(position & (termLength - 1))
2. Correct negative values that result from signed arithmetic on positions
3. Use initialPosition(position, initialTermId, termLength) instead, which computes the offset correctly for you

Example fix

// before
builder.termOffset(-64); // throws
// after
builder.termOffset(1024);

if (termOffset != null && (termOffset < 0 || termOffset > (1 << 30))) throw new IllegalArgumentException("term offset out of range: " + termOffset);

try { builder.termOffset(offset); } catch (IllegalArgumentException e) { /* clamp or recompute offset */ }

When it happens

Trigger: Calling termOffset() with a negative Integer or one greater than 1073741824, or a URI with 'term-offset=-100' / 'term-offset=2000000000'.

Common situations: Computing an offset from a position without masking it into the term; mixing units (bytes vs. offset); resuming a publication with a stale/wrong offset captured from a different term length.

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

• term length more than max length of
• invalid position= < 0
• 'initial-term-id' must be a valid integer
• 'term-id' must be a valid integer
• term offset not multiple of FRAME_ALIGNMENT

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

Appendix: source

Thrown at aeron-client/src/main/java/io/aeron/ChannelUriStringBuilder.java:838

    {
        return termId;
    }

    /**
     * Set the offset within a term at which a publication will start. This when combined with the term id can establish
     * a starting position.
     *
     * @param termOffset within a term at which a publication will start.
     * @return this for a fluent API.
     * @see CommonContext#TERM_OFFSET_PARAM_NAME
     */
    public ChannelUriStringBuilder termOffset(final Integer termOffset)
    {
        if (null != termOffset)
        {
            if ((termOffset < 0 || termOffset > TERM_MAX_LENGTH))
            {
                throw new IllegalArgumentException("term offset not in range 0-1g: " + termOffset);
            }

            if (0 != (termOffset & (FRAME_ALIGNMENT - 1)))
            {
                throw new IllegalArgumentException("term offset not multiple of FRAME_ALIGNMENT: " + termOffset);
            }
        }

        this.termOffset = termOffset;
        return this;
    }

    /**
     * Set the termOffset value to be what is in the {@link ChannelUri} which may be null.
     *
     * @param channelUri to read the value from.
     * @return this for a fluent API.
     * @see CommonContext#TERM_OFFSET_PARAM_NAME

View on GitHub (pinned to 6d60124e15)