aeron-io/aeron · error · InvalidChannelException

invalid , must be a number

Error message

invalid <paramName>, must be a number

What it means

parseInt converts a channel URI parameter string to an int and throws InvalidChannelException when Integer.parseInt fails, i.e. the value is not a valid signed 32-bit integer. It is applied to params like stream-id, session-id, and max-resend when parsing publication params.

Solutions

  1. Ensure the parameter value is a plain integer string, e.g. stream-id=1001
  2. Trim whitespace and strip formatting from the value before building the URI
  3. Log/echo the full channel URI in the InvalidChannelException cause to find which param is bad
  4. Parse/validate with Integer.parseInt in your own config loader before constructing the URI

Example fix

// before
String uri = "aeron:udp?endpoint=localhost:40456|stream-id=" + streamName; // streamName="market-data"
// after
String uri = "aeron:udp?endpoint=localhost:40456|stream-id=" + Integer.parseInt(streamIdConfig);
Defensive patterns

Strategy: validation

Validate before calling

int v;
try { v = Integer.parseInt(value.trim()); }
catch (NumberFormatException e) { throw new IllegalArgumentException(paramName + " must be an integer, got: " + value); }

Type guard

boolean isIntParam(String v) {
    try { Integer.parseInt(v == null ? "" : v.trim()); return true; } catch (NumberFormatException e) { return false; }
}

Try / catch

try { publication = aeron.addPublication(uri, streamId); }
catch (InvalidChannelException e) {
    if (e.getCause() instanceof NumberFormatException) {
        throw new ConfigurationException("Non-numeric URI parameter in: " + uri, e);
    } throw e;
}

Prevention

When it happens

Trigger: Any channel URI param parsed as int contains non-numeric text (e.g. `session-id=abc`, `stream-id=1_000`, `max-resend=6.0`), or an empty value; the thrown message names the offending param.

Common situations: Interpolating strings/symbols into URI templates; locale-formatted numbers with separators or decimals; trailing whitespace; passing a session name instead of id; YAML/properties values silently typed as strings like '1024\n'.

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

Appendix: source

Thrown at aeron-driver/src/main/java/io/aeron/driver/PublicationParams.java:550

            if (maxResend <= 0 || maxResend > Configuration.MAX_RESEND_MAX)
            {
                throw new InvalidChannelException(
                    "invalid " + MAX_RESEND_PARAM_NAME + "=" + maxResend +
                    ", must be > 0 and <= " + Configuration.MAX_RESEND_MAX);
            }
        }
    }

    private static int parseInt(final String value, final String paramName)
    {
        try
        {
            return Integer.parseInt(value);
        }
        catch (final NumberFormatException ex)
        {
            throw new InvalidChannelException(
                "invalid " + paramName + ", must be a number", ex);
        }
    }

    private static long parseLong(final String value, final String paramName)
    {
        try
        {
            return Long.parseLong(value);
        }
        catch (final NumberFormatException ex)
        {
            throw new InvalidChannelException(
                "invalid " + paramName + ", must be a number", ex);
        }
    }

    private static long parseResponseCorrelationId(final ChannelUri channelUri)

View on GitHub (pinned to 6d60124e15)