What causes "TTL not in range 0-255: ${ttl}" in aeron-io/aeron?

Clamp or validate the value to [0, 255] before calling ttl().

aeron-io/aeron · error · IllegalArgumentException

TTL not in range 0-255

Error message

TTL not in range 0-255: ${ttl}

What it means

Input validation guard in the fluent builder's ttl(Integer) setter. The ttl sets the Time To Live (hop count) for multicast datagrams, which must fit in a single unsigned byte (0-255). The exception fires when the caller supplies a null-checked non-null ttl value below 0 or above 255, rejecting the builder configuration before the value is stored for use in the channel URI's ttl= parameter.

Solutions

Clamp or validate the value to [0, 255] before calling ttl().
Use a typical multicast TTL such as 1-16 depending on network scope.
Omit ttl() if the default is acceptable.

Example fix

// before
builder.ttl(512);
// after
builder.ttl(Math.min(255, Math.max(0, configuredTtl)));

Defensive patterns

Strategy: validation

Validate before calling

if (ttl != null && (ttl < 0 || ttl > 255)) { throw new IllegalArgumentException("TTL not in range 0-255: " + ttl); }

Type guard

boolean isValidTtl(Integer ttl) { return ttl == null || (ttl >= 0 && ttl <= 255); }

Try / catch

try { builder.ttl(t); } catch (IllegalArgumentException e) { builder.ttl(1); }

Prevention

Clamp config values to [0,255] at load time
Remember TTL is hop count, not milliseconds
Use small TTLs (1-16) for multicast scoping

When it happens

Trigger: builder.ttl(256), builder.ttl(-1), or passing a parsed config value without range checking.

Common situations: Using OS defaults larger than 255; sign errors when reading config; computing TTL as a millisecond value instead of hop count.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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

Appendix: source

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

public ChannelUriStringBuilder ttl(final Integer ttl)
{
    if (null != ttl && (ttl < 0 || ttl > 255))
    {
        throw new IllegalArgumentException("TTL not in range 0-255: " + ttl);
    }

    this.ttl = ttl;
    return this;
}

View on GitHub (pinned to 6d60124e15)