aeron-io/aeron · error · IllegalArgumentException

'term-offset' must be a valid integer

Error message

'term-offset' must be a valid integer

What it means

ChannelUriStringBuilder.termOffset(String) parses the 'term-offset' URI parameter with Integer.valueOf and converts NumberFormatException into this IllegalArgumentException. It indicates the 'term-offset' value in the channel URI is not a valid signed 32-bit integer, independent of the later range/alignment checks.

Solutions

1. Fix the term-offset value in the URI to a plain integer (e.g. term-offset=1024)
2. Validate the string with Integer.parseInt before use and surface a clearer error
3. Remember additional constraints: after parsing, the value must also be in 0..1g and a multiple of 32

Example fix

// before
String uri = "aeron:udp?endpoint=h:40456|term-offset=0x400"; // hex not parsed
// after
String uri = "aeron:udp?endpoint=h:40456|term-offset=1024";

try { Integer.parseInt(termOffsetValue); } catch (NumberFormatException e) { throw new IllegalArgumentException("invalid term-offset: " + termOffsetValue); }

try { builder.termOffset(uriValue); } catch (IllegalArgumentException e) { log.error("term-offset must be int32", e); }

When it happens

Trigger: Passing a URI like 'aeron:udp?...|term-offset=abc', 'term-offset=1.5', 'term-offset=', or a value above Integer.MAX_VALUE.

Common situations: Template URIs with unsubstituted placeholders; copy/paste from documentation where the value was example text; formatting bugs producing decimal or empty strings.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• 'initial-term-id' must be a valid integer
• 'term-id' must be a valid integer
• 'session-id' must be a valid integer
• 'gtag' must be a valid long value
• 'ttl' must be a value integer

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

Appendix: source

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

     * @see CommonContext#TERM_OFFSET_PARAM_NAME
     */
    public ChannelUriStringBuilder termOffset(final ChannelUri channelUri)
    {
        final String termOffsetValue = channelUri.get(TERM_OFFSET_PARAM_NAME);
        if (null == termOffsetValue)
        {
            termOffset = null;
            return this;
        }
        else
        {
            try
            {
                return termOffset(Integer.valueOf(termOffsetValue));
            }
            catch (final NumberFormatException ex)
            {
                throw new IllegalArgumentException("'term-offset' must be a valid integer", ex);
            }
        }
    }

    /**
     * Get the offset within a term at which a publication will start.
     *
     * @return the offset within a term at which a publication will start.
     * @see CommonContext#TERM_OFFSET_PARAM_NAME
     */
    public Integer termOffset()
    {
        return termOffset;
    }

    /**
     * Set the session id for a publication or restricted subscription.
     *

View on GitHub (pinned to 6d60124e15)