aeron-io/aeron · error · ConfigurationException

untetheredLingerTimeoutNs=

Error message

untetheredLingerTimeoutNs=${untetheredLingerTimeoutNs} <= timerIntervalNs=${timerIntervalNs}

What it means

Aeron driver configuration validation: the untethered linger timeout must be strictly greater than the driver timer interval, otherwise the timeout can never be observed by the timer wheel. The driver throws ConfigurationException during configuration validation (when the value is set and not NULL_VALUE).

Solutions

1. Increase untetheredLingerTimeoutNs to be strictly greater than timerIntervalNs (e.g. >= 2x the timer interval)
2. Or leave untetheredLingerTimeoutNs as Aeron.NULL_VALUE to use the default and keep the timer interval unchanged
3. Reduce timerIntervalNs if a sub-second linger timeout is truly required, keeping linger > interval

Example fix

// before
ctx.untetheredLingerTimeoutNs(500_000_000); // 0.5s <= default 1s timer interval -> throws
// after
ctx.untetheredLingerTimeoutNs(2_000_000_000); // 2s > 1s timer interval

if (untetheredLingerTimeoutNs != Aeron.NULL_VALUE && untetheredLingerTimeoutNs <= ctx.timerIntervalNs()) { throw new IllegalArgumentException("untetheredLingerTimeoutNs must be > timerIntervalNs"); }

When it happens

Trigger: Setting Aeron context untetheredLingerTimeout (e.g. context.untetheredLingerTimeoutNs(...)) to a positive value that is less than or equal to the configured timerIntervalNs (default 1 second). Also triggered by system property aeron.driver.untethered.linger.timeout set too low.

Common situations: Developers tune untethered subscription behavior for low-latency or short-lived connections and set a sub-second linger timeout without realizing the driver timer only fires every timerIntervalNs (default 1s).

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• newLeaderTimeoutNs must be positive or -1, but was
• mtuLength= > initialWindowLength=
• mtuLength= <= HEADER_LENGTH=
• publicationUnblockTimeoutNs=
• clientLivenessTimeoutNs=

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

Appendix: source

Thrown at aeron-driver/src/main/java/io/aeron/driver/Configuration.java:2642

        final long timerIntervalNs)
    {
        if (untetheredWindowLimitTimeoutNs <= timerIntervalNs)
        {
            throw new ConfigurationException(
                "untetheredWindowLimitTimeoutNs=" + untetheredWindowLimitTimeoutNs +
                " <= timerIntervalNs=" + timerIntervalNs);
        }

        if (untetheredRestingTimeoutNs <= timerIntervalNs)
        {
            throw new ConfigurationException(
                "untetheredRestingTimeoutNs=" + untetheredRestingTimeoutNs +
                " <= timerIntervalNs=" + timerIntervalNs);
        }

        if (Aeron.NULL_VALUE != untetheredLingerTimeoutNs && untetheredLingerTimeoutNs <= timerIntervalNs)
        {
            throw new ConfigurationException(
                "untetheredLingerTimeoutNs=" + untetheredLingerTimeoutNs +
                    " <= timerIntervalNs=" + timerIntervalNs);
        }
    }

    /**
     * Create a source identity for a given source address.
     *
     * @param srcAddress to be used for the identity.
     * @return a source identity string for a given address.
     */
    public static String sourceIdentity(final InetSocketAddress srcAddress)
    {
        return srcAddress.getHostString() + ':' + srcAddress.getPort();
    }

    static void validateValueRange(final long value, final long minValue, final long maxValue, final String name)
    {

View on GitHub (pinned to 6d60124e15)