aeron-io/aeron · error · IllegalArgumentException

must be a number

Error message

${STREAM_ID_PARAM_NAME} must be a number

What it means

Thrown by ChannelUriStringBuilder when the streamId URI parameter string cannot be parsed as an integer. The builder validates all URI components before constructing the channel string, so a non-numeric stream-id fails fast instead of producing a malformed channel URI. The original NumberFormatException is preserved as the cause.

Solutions

1. Pass the stream id as an int via streamId(int) instead of a String to avoid parsing entirely.
2. Validate the string with Integer.parseInt (or a regex like \\-?\\d+) before calling streamId(String).
3. Trim the string and fix environment/config sources supplying the value.

Example fix

// before
builder.streamId(System.getenv("STREAM_ID")); // "1001 " -> IllegalArgumentException
// after
String raw = System.getenv("STREAM_ID").trim();
int streamId = Integer.parseInt(raw); // fail with clear message, or use builder.streamId(streamId)

int streamId;
try { streamId = Integer.parseInt(raw.trim()); }
catch (NumberFormatException e) { throw new IllegalArgumentException("stream-id must be an integer, got: " + raw, e); }
builder.streamId(streamId);

try { builder.streamId(raw); } catch (IllegalArgumentException e) { log.error("bad stream-id URI param: {}", e.getMessage()); }

When it happens

Trigger: Calling ChannelUriStringBuilder.streamId(String) with a value that Integer.parseInt cannot parse: non-numeric text, floating point (e.g. "1.5"), leading/trailing whitespace, or an empty string.

Common situations: Building channel URIs from environment variables or config files where the stream-id was entered as text; string substitution leaving placeholders like "${streamId}" unexpanded; copying a URI where stream-id was accidentally replaced by a label.

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

• 'ttl' must be a value integer
• must be a number
• ` ` value cannot be negative
• invalid , must be a number
• invalid position

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

Appendix: source

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

     * @return this for a fluent API.
     */
    public ChannelUriStringBuilder streamId(final ChannelUri channelUri)
    {
        final String valueStr = channelUri.get(STREAM_ID_PARAM_NAME);
        if (null == valueStr)
        {
            this.streamId = null;
            return this;
        }
        else
        {
            try
            {
                return streamId(Integer.parseInt(valueStr));
            }
            catch (final NumberFormatException ex)
            {
                throw new IllegalArgumentException(STREAM_ID_PARAM_NAME + " must be a number", ex);
            }
        }
    }

    /**
     * Set the publication window length which defines how far ahead can publication accept offers.
     *
     * @param publicationWindowLength of the channel.
     * @return this for a fluent API.
     * @see CommonContext#PUBLICATION_WINDOW_LENGTH_PARAM_NAME
     */
    public ChannelUriStringBuilder publicationWindowLength(final Integer publicationWindowLength)
    {
        this.publicationWindowLength =
            requireNonNegative(publicationWindowLength, PUBLICATION_WINDOW_LENGTH_PARAM_NAME);
        return this;
    }

View on GitHub (pinned to 6d60124e15)