aeron-io/aeron · error · ConfigurationException

clientLivenessTimeoutNs=

Error message

clientLivenessTimeoutNs=${clientLivenessTimeoutNs} <= timerIntervalNs=${timerIntervalNs}

What it means

Configuration.validateUnblockTimeout also requires the client liveness timeout to be strictly greater than the timer interval; the driver's housekeeping timer must tick faster than the liveness timeout for client death to be detected in a timely and correct manner. A ConfigurationException is thrown when clientLivenessTimeoutNs <= timerIntervalNs.

Solutions

1. Increase aeron.client.liveness.timeout so it is strictly greater than aeron.timer.interval
2. Or decrease aeron.timer.interval so it ticks several times within the liveness timeout
3. Keep ordering: timerInterval < clientLivenessTimeout < publicationUnblockTimeout

Example fix

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

long timer = TimeUnit.MILLISECONDS.toNanos(100);
long liveness = TimeUnit.SECONDS.toNanos(1);
if (liveness <= timer) throw new IllegalStateException("clientLivenessTimeout must be > timerInterval");
io.aeron.driver.Configuration.validateUnblockTimeout(TimeUnit.SECONDS.toNanos(15), liveness, timer);

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

When it happens

Trigger: Calling validateUnblockTimeout with aeron.client.liveness.timeout <= aeron.timer.interval, e.g. clientLivenessTimeoutNs=500ms with timerIntervalNs=1s.

Common situations: Aggressively lowering the liveness timeout for fast failover without speeding up the timer; raising the timer interval to reduce CPU usage; inconsistent values between driver and client defaults after an upgrade.

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

• publicationUnblockTimeoutNs=
• segment file length not a power of 2
• segment file length not in valid range
• AeronArchive.Context.messageRetryAttempts must be > 0, got:
• difference greater than 2^31 - 1: termId=

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

Appendix: source

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

     *
     * @param publicationUnblockTimeoutNs after which an uncommitted publication will be unblocked.
     * @param clientLivenessTimeoutNs     after which a client will be considered not alive.
     * @param timerIntervalNs             interval at which the driver will check timeouts.
     * @throws ConfigurationException if the values are not valid.
     */
    public static void validateUnblockTimeout(
        final long publicationUnblockTimeoutNs, final long clientLivenessTimeoutNs, final long timerIntervalNs)
    {
        if (publicationUnblockTimeoutNs <= clientLivenessTimeoutNs)
        {
            throw new ConfigurationException(
                "publicationUnblockTimeoutNs=" + publicationUnblockTimeoutNs +
                " <= clientLivenessTimeoutNs=" + clientLivenessTimeoutNs);
        }

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

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

View on GitHub (pinned to 6d60124e15)