aeron-io/aeron · error · ConfigurationException

untetheredRestingTimeoutNs=

Error message

untetheredRestingTimeoutNs=${untetheredRestingTimeoutNs} <= timerIntervalNs=${timerIntervalNs}

What it means

Configuration.validateUntetheredTimeouts also requires the untethered resting timeout to be strictly greater than the driver timer interval, ensuring the resting state of an untethered subscription is evaluated on a sane timescale. A ConfigurationException is thrown when untetheredRestingTimeoutNs <= timerIntervalNs.

Solutions

1. Raise aeron.untethered.resting.timeout so it is strictly greater than aeron.timer.interval
2. Or decrease aeron.timer.interval
3. Verify ordering: timerInterval < windowLimitTimeout, timerInterval < restingTimeout, and (if set) timerInterval < lingerTimeout

Example fix

// before
ctx.timerIntervalNs(TimeUnit.SECONDS.toNanos(1));
ctx.untetheredRestingTimeoutNs(TimeUnit.MILLISECONDS.toNanos(200));
// after
ctx.timerIntervalNs(TimeUnit.SECONDS.toNanos(1));
ctx.untetheredRestingTimeoutNs(TimeUnit.SECONDS.toNanos(10)); // > timerInterval

long timer = TimeUnit.MILLISECONDS.toNanos(100);
long resting = TimeUnit.SECONDS.toNanos(10);
if (resting <= timer) throw new IllegalStateException("untetheredRestingTimeout must be > timerInterval");
io.aeron.driver.Configuration.validateUntetheredTimeouts(windowLimitTimeout, resting, lingerTimeout, timer);

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

When it happens

Trigger: Calling validateUntetheredTimeouts with aeron.untethered.resting.timeout <= aeron.timer.interval, e.g. restingTimeout=200ms with timerInterval=1s.

Common situations: Tuning resting timeout very low for quick reactivation of untethered subscriptions; timer interval raised for CPU savings; config assembled from mixed sources.

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

• untetheredWindowLimitTimeoutNs=
• 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/1b2d4e56b88ea7bd. Report an issue: GitHub.

Appendix: source

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

     * @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);
        }
    }

    /**
     * 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.
     */

View on GitHub (pinned to 6d60124e15)