aeron-io/aeron · error · IllegalArgumentException

'ttl' must be a value integer

Error message

'ttl' must be a value integer

What it means

Thrown by the builder's ttl(String) parse path when the 'ttl' URI parameter value cannot be parsed as an integer. The original NumberFormatException is wrapped as an IllegalArgumentException so callers get a consistent builder validation exception.

Solutions

1. Correct the URI parameter so ttl is a decimal integer, e.g. aeron:udp?ttl=16.
2. Validate the string with Integer.parseInt in a guard before building.
3. Strip default/placeholder values from config before constructing the URI.

Example fix

// before
builder.ttl(uri.get("ttl")); // ttl=fast
// after
String v = uri.get("ttl");
if (v != null && v.matches("\\d+")) builder.ttl(v);

String v = uriParam("ttl");
if (v != null && !v.matches("\\d+")) { throw new IllegalArgumentException("'ttl' must be a value integer"); }

boolean isIntegerString(String s) { if (s == null || s.isEmpty()) return false; try { Integer.parseInt(s); return true; } catch (NumberFormatException e) { return false; } }

try { builder.ttl(rawTtl); } catch (IllegalArgumentException e) { /* fall back to default ttl */ }

When it happens

Trigger: ttlUriParameterValue("fast") or a URI containing ttl=abc passed through builder.ttl(...String...) — Integer.valueOf throws NumberFormatException which is rethrown with this message.

Common situations: Hand-edited channel URIs with a non-numeric ttl; environment/config substitution that injects an empty or placeholder string; copying a URI with a malformed query parameter.

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

• >
• must be a number
• must be a number
• invalid , must be a number
• invalid entity tag, must be a number

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

Appendix: source

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

     * @see CommonContext#TTL_PARAM_NAME
     */
    public ChannelUriStringBuilder ttl(final ChannelUri channelUri)
    {
        final String ttlValue = channelUri.get(TTL_PARAM_NAME);
        if (null == ttlValue)
        {
            ttl = null;
            return this;
        }
        else
        {
            try
            {
                return ttl(Integer.valueOf(ttlValue));
            }
            catch (final NumberFormatException ex)
            {
                throw new IllegalArgumentException("'ttl' must be a value integer", ex);
            }
        }
    }

    /**
     * Get the Time To Live (TTL) for a multicast datagram.
     *
     * @return the Time To Live (TTL) for a multicast datagram.
     * @see CommonContext#TTL_PARAM_NAME
     */
    public Integer ttl()
    {
        return ttl;
    }

    /**
     * Set the maximum transmission unit (MTU) including Aeron header for a datagram payload. If this is greater
     * than the network MTU for UDP then the packet will be fragmented and can amplify the impact of loss.

View on GitHub (pinned to 6d60124e15)