What causes "'initial-term-id' must be a valid integer" in aeron-io/aeron?

Fix the initial-term-id value in the URI to a signed 32-bit integer (e.g. -123456789 or 42)

aeron-io/aeron · error · IllegalArgumentException

'initial-term-id' must be a valid integer

Error message

'initial-term-id' must be a valid integer

What it means

When building from a parsed channel URI, ChannelUriStringBuilder.initialTermId() reads the 'initial-term-id' parameter and converts it with Integer.valueOf. If the string is not a valid 32-bit integer (empty, alphabetic, out of int range), it is rethrown as IllegalArgumentException with this message and the NumberFormatException as cause. This indicates a malformed URI parameter value.

Solutions

Fix the initial-term-id value in the URI to a signed 32-bit integer (e.g. -123456789 or 42)
If the value is computed as a long, mask or cast to int before formatting: (int)initialTermId
Validate with Integer.parseInt(value) inside try-catch before building the URI

Example fix

// before
String uri = "aeron:udp?endpoint=localhost:40456|initial-term-id=1x0";
// after
String uri = "aeron:udp?endpoint=localhost:40456|initial-term-id=100";

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

try { builder.initialTermId(uriValue); } catch (IllegalArgumentException e) { /* handle NumberFormatException cause */ }

Prevention

Cast long term ids to int before formatting into URIs
Never build URIs by raw string concatenation of numeric fields; use ChannelUriStringBuilder
Validate URI parameters with Integer.parseInt before use

When it happens

Trigger: Passing a channel URI whose initial-term-id value is non-numeric, e.g. 'aeron:udp?...|initial-term-id=abc' or 'initial-term-id=99999999999' (exceeds int range).

Common situations: Manual URI editing with typos; generating URIs with long/64-bit term IDs from a different system; string concatenation bugs producing empty or partially formatted values.

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

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

Appendix: source

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

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

    /**
     * the initial term id at which a publication will start.
     *
     * @return the initial term id at which a publication will start.
     * @see CommonContext#INITIAL_TERM_ID_PARAM_NAME
     */
    public Integer initialTermId()
    {
        return initialTermId;
    }

    /**
     * Set the current term id at which a publication will start. This when combined with the initial term can
     * establish a starting position.

View on GitHub (pinned to 6d60124e15)