What causes "`${name}` value cannot be negative: ${value}" in aeron-io/aeron?

Use a positive value for the named field (the exception message contains the field name and value).

aeron-io/aeron · error · IllegalArgumentException

` ` value cannot be negative

Error message

`${name}` value cannot be negative: ${value}

What it means

Thrown by ChannelUriStringBuilder's private requireNonNegative(Long, String) helper when an optional numeric URI field is set to a negative Long value. The builder refuses to emit channel URIs with negative sizes/ids because the media driver would reject or misinterpret them.

Solutions

Use a positive value for the named field (the exception message contains the field name and value).
Leave the field null/unset instead of using -1 as a sentinel.
Clamp or validate values computed from arithmetic before passing them to the builder.

Example fix

// before
long window = computeWindow(); // may be -1 when missing
builder.initialWindowLength(window);
// after
if (window >= 0) builder.initialWindowLength(window); // otherwise leave unset

Defensive patterns

Strategy: validation

Validate before calling

if (value != null && value < 0) throw new IllegalArgumentException(name + " must be non-negative, got " + value);
builder.initialWindowLength(value);

Try / catch

try { uri = builder.build(); } catch (IllegalArgumentException e) { /* includes non-negative violations; log field name from message */ log.error("invalid channel field: {}", e.getMessage()); }

Prevention

Do not use -1 as an 'unset' sentinel; leave fields null.
Guard arithmetic that can underflow below zero.
Validate all sizes when loading config, before building the URI.

When it happens

Trigger: Setting a Long-typed builder field (e.g. initialWindowLength, termBufferLength, session-id related tagged values) via a setter that runs requireNonNegative with a negative value such as -1.

Common situations: Using -1 as a sentinel 'unset' value when configuring from properties; unsigned sizes computed with arithmetic underflow (e.g. capacity - overhead going negative).

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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

Appendix: source

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

        if (null != valueNs)
        {
            sb.append(paramName).append('=').append(SystemUtil.formatDuration(valueNs)).append('|');
        }
    }

    private static void appendSize(final StringBuilder sb, final String paramName, final Integer value)
    {
        if (null != value)
        {
            sb.append(paramName).append('=').append(SystemUtil.formatSize(value)).append('|');
        }
    }

    private static Long requireNonNegative(final Long value, final String name)
    {
        if (null != value && value < 0)
        {
            throw new IllegalArgumentException("`" + name + "` value cannot be negative: " + value);
        }
        return value;
    }

    private static Integer requireNonNegative(final Integer value, final String name)
    {
        if (null != value && value < 0)
        {
            throw new IllegalArgumentException("`" + name + "` value cannot be negative: " + value);
        }
        return value;
    }

    private static String prefixTag(final boolean isTagged, final Long value)
    {
        return isTagged ? TAG_PREFIX + value : value.toString();
    }
}

View on GitHub (pinned to 6d60124e15)