aeron-io/aeron · error · ConfigurationException

untetheredWindowLimitTimeoutNs=

Error message

untetheredWindowLimitTimeoutNs=${untetheredWindowLimitTimeoutNs} <= timerIntervalNs=${timerIntervalNs}

What it means

Configuration.validateUntetheredTimeouts checks that the untethered window limit timeout is strictly greater than the driver timer interval, so untethered subscriptions are managed on a timescale meaningful relative to driver housekeeping ticks. A ConfigurationException is thrown when untetheredWindowLimitTimeoutNs <= timerIntervalNs.

Solutions

1. Raise aeron.untethered.window.limit.timeout so it is strictly greater than aeron.timer.interval
2. Or lower aeron.timer.interval
3. Audit all untethered timeouts together against the timer interval

Example fix

// before
ctx.timerIntervalNs(TimeUnit.SECONDS.toNanos(1));
ctx.untetheredWindowLimitTimeoutNs(TimeUnit.MILLISECONDS.toNanos(100));
// after
ctx.timerIntervalNs(TimeUnit.SECONDS.toNanos(1));
ctx.untetheredWindowLimitTimeoutNs(TimeUnit.SECONDS.toNanos(5)); // > timerInterval

long timer = TimeUnit.MILLISECONDS.toNanos(100);
long windowLimit = TimeUnit.SECONDS.toNanos(5);
if (windowLimit <= timer) throw new IllegalStateException("untetheredWindowLimitTimeout must be > timerInterval");
io.aeron.driver.Configuration.validateUntetheredTimeouts(windowLimit, restingTimeout, lingerTimeout, timer);

try {
    ctx.conclude();
} catch (ConfigurationException e) {
    if (e.getMessage().contains("untetheredWindowLimitTimeoutNs")) {
        ctx.untetheredWindowLimitTimeoutNs(ctx.timerIntervalNs() * 10);
        ctx.conclude();
    } else { throw e; }
}

When it happens

Trigger: Calling validateUntetheredTimeouts with aeron.untethered.window.limit.timeout <= aeron.timer.interval, e.g. windowLimitTimeout=100ms with timerInterval=1s.

Common situations: Shrinking untethered timeouts to reclaim subscriptions quickly while leaving the timer interval at its default; bulk-copying timeout values without checking interdependencies.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

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

Related errors

• untetheredRestingTimeoutNs=
• clientLivenessTimeoutNs=
• publicationUnblockTimeoutNs=
• Aeron client instance must set…
• Aeron client must use a RethrowingErrorHandler

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

Appendix: source

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

    /**
     * Validate that the timeouts for untethered subscriptions are greater than timer interval.
     *
     * @param untetheredWindowLimitTimeoutNs after which an active untethered subscription will be lingered.
     * @param untetheredLingerTimeoutNs      after which a lingering untethered subscription will transition to resting.
     * @param untetheredRestingTimeoutNs     after which a resting untethered subscription will become active again.
     * @param timerIntervalNs                interval at which the driver will check timeouts.
     * @throws ConfigurationException if the values are not valid.
     */
    public static void validateUntetheredTimeouts(
        final long untetheredWindowLimitTimeoutNs,
        final long untetheredLingerTimeoutNs,
        final long untetheredRestingTimeoutNs,
        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);
        }
    }

View on GitHub (pinned to 6d60124e15)