aeron-io/aeron · error · IllegalArgumentException

'term-id' must be a valid integer

Error message

'term-id' must be a valid integer

What it means

ChannelUriStringBuilder.termId() converts the 'term-id' URI parameter with Integer.valueOf and wraps any NumberFormatException as IllegalArgumentException with this message. The 'term-id' must be a valid signed 32-bit integer because term IDs are int values in Aeron's positioning scheme.

Solutions

1. Correct the term-id value to a signed 32-bit integer in the URI
2. If the id is a long, convert with (int)termId or Math.toIntExact plus masking before formatting
3. Pre-validate the string with Integer.parseInt in a try-catch before constructing the URI

Example fix

// before
builder.termId("5294967296"); // exceeds int range
// after
builder.termId("1000000000");

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

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

When it happens

Trigger: Passing a channel URI with a non-integer 'term-id' value, e.g. '|term-id=abc', '|term-id=3.5', or a value beyond Integer.MAX_VALUE such as a 64-bit id.

Common situations: Copy-pasted URIs from logs where the term id was printed as a long; template URIs with placeholder text not substituted; computed ids wider than int.

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

Appendix: source

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

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

    /**
     * Get the current term id at which a publication will start.
     *
     * @return the current term id at which a publication will start.
     * @see CommonContext#TERM_ID_PARAM_NAME
     */
    public Integer termId()
    {
        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.

View on GitHub (pinned to 6d60124e15)