aeron-io/aeron · error · IllegalArgumentException

' ' does not contain a valid long value

Error message

'${paramName}' does not contain a valid long value

What it means

Generic numeric parsing helper used when reading optional long-valued URI parameters (e.g. group-tag via groupTag()). It fetches the named parameter from the channel URI and attempts Long.valueOf. The exception fires when the parameter is present in the URI but its text cannot be parsed as a signed 64-bit long, wrapping the NumberFormatException to name the offending parameter.

Solutions

1. Provide the group tag as a plain decimal long, e.g. group-tag=123456789
2. Remove the parameter if grouping is not needed
3. Verify no template placeholders or whitespace remain in the value

Example fix

// before
"aeron:udp?endpoint=...|group-tag=0x1F"
// after
"aeron:udp?endpoint=...|group-tag=31"

String v = uri.getParam("group-tag"); if (v != null) Long.parseLong(v.trim());

static boolean isLong(String v) { try { Long.parseLong(v.trim()); return true; } catch (NumberFormatException e) { return false; } }

try { channel = aeron.addPublication(uri, stream); } catch (InvalidChannelException e) { if (e.getCause() instanceof NumberFormatException) { /* fix group-tag */ } throw e; }

When it happens

Trigger: Passing group-tag=abc or a value exceeding 64-bit range in the channel URI; parseOptionalLong is invoked from groupTag parsing.

Common situations: Hex or decimal-prefixed strings ('0x1f') that Long.valueOf rejects, typos, or values copied from another system's format.

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

• invalid position
• URI length ( ) exceeds max supported length ( )…
• Aeron URIs must start with 'aeron:', found
• encountered ' ' within media definition at index in
• difference greater than 2^31 - 1: termId=

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

Appendix: source

Thrown at aeron-driver/src/main/java/io/aeron/driver/media/UdpChannel.java:341

private static Long parseOptionalLong(final ChannelUri channelUri, final String paramName)
{
    final String longAsString = channelUri.get(paramName);
    if (null == longAsString)
    {
        return null;
    }

    try
    {
        return Long.valueOf(longAsString);
    }
    catch (final NumberFormatException ex)
    {
        throw new IllegalArgumentException("'" + paramName + "' does not contain a valid long value", ex);
    }
}

View on GitHub (pinned to 6d60124e15)