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

Correct the session-id value in the URI to a signed 32-bit integer

aeron-io/aeron · error · IllegalArgumentException

'session-id' must be a valid integer

Error message

'session-id' must be a valid integer

What it means

When initializing from a channel URI, the builder parses the 'session-id' parameter with Integer.valueOf and wraps NumberFormatException as this IllegalArgumentException. Session ids are 32-bit ints in Aeron, so the URI value must be a valid signed integer (negative values are allowed for sparse session ids).

Solutions

Correct the session-id value in the URI to a signed 32-bit integer
Cast a long session id to int before formatting: (int)sessionId
Pre-validate the string with Integer.parseInt in a try-catch

Example fix

// before
String uri = "aeron:udp?endpoint=h:40456|session-id=42L"; // suffix not accepted
// after
String uri = "aeron:udp?endpoint=h:40456|session-id=42";

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

try { builder.sessionId(sessionIdStr); } catch (IllegalArgumentException e) { /* regenerate or fix session id */ }

Prevention

Cast long session ids to int before URI formatting
Let Aeron auto-assign session ids instead of hardcoding them when possible
Use ChannelUriStringBuilder.sessionId(Integer) with typed values

When it happens

Trigger: A channel URI containing 'session-id=abc', 'session-id=12345678901', or an empty value, passed to ChannelUriStringBuilder.validate()/initialiseFromUri.

Common situations: Hand-edited URIs; generating session ids as longs and concatenating without casting; placeholder text left in configuration templates.

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/44d0bebe53422c6e. Report an issue: GitHub.

Appendix: source

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

     */
    public ChannelUriStringBuilder sessionId(final String sessionIdStr)
    {
        if (null != sessionIdStr)
        {
            if (ChannelUri.isTagged(sessionIdStr))
            {
                taggedSessionId(ChannelUri.getTag(sessionIdStr));
            }
            else
            {
                isSessionIdTagged(false);
                try
                {
                    sessionId(Integer.valueOf(sessionIdStr));
                }
                catch (final NumberFormatException ex)
                {
                    throw new IllegalArgumentException("'session-id' must be a valid integer", ex);
                }
            }
        }
        else
        {
            sessionId((Integer)null);
        }

        return this;
    }

    /**
     * Set the session id for a publication or restricted subscription as a tag referenced value.
     *
     * @param sessionId for the publication or a restricted subscription.
     * @return this for a fluent API.
     * @see CommonContext#SESSION_ID_PARAM_NAME
     */

View on GitHub (pinned to 6d60124e15)