{"record":{"id":"930b565548341ad9","repo":"aeron-io/aeron","slug":"clientlivenesstimeoutns-clientlivenesstimeoutns","errorCode":null,"errorMessage":"clientLivenessTimeoutNs=${clientLivenessTimeoutNs} <= timerIntervalNs=${timerIntervalNs}","messagePattern":"clientLivenessTimeoutNs=(.+?) <= timerIntervalNs=(.+?)","errorType":"validation","errorClass":"ConfigurationException","httpStatus":null,"severity":"error","filePath":"aeron-driver/src/main/java/io/aeron/driver/Configuration.java","lineNumber":2605,"sourceCode":"     *\n     * @param publicationUnblockTimeoutNs after which an uncommitted publication will be unblocked.\n     * @param clientLivenessTimeoutNs     after which a client will be considered not alive.\n     * @param timerIntervalNs             interval at which the driver will check timeouts.\n     * @throws ConfigurationException if the values are not valid.\n     */\n    public static void validateUnblockTimeout(\n        final long publicationUnblockTimeoutNs, final long clientLivenessTimeoutNs, final long timerIntervalNs)\n    {\n        if (publicationUnblockTimeoutNs <= clientLivenessTimeoutNs)\n        {\n            throw new ConfigurationException(\n                \"publicationUnblockTimeoutNs=\" + publicationUnblockTimeoutNs +\n                \" <= clientLivenessTimeoutNs=\" + clientLivenessTimeoutNs);\n        }\n\n        if (clientLivenessTimeoutNs <= timerIntervalNs)\n        {\n            throw new ConfigurationException(\n                \"clientLivenessTimeoutNs=\" + clientLivenessTimeoutNs +\n                \" <= timerIntervalNs=\" + timerIntervalNs);\n        }\n    }\n\n    /**\n     * Validate that the timeouts for untethered subscriptions are greater than timer interval.\n     *\n     * @param untetheredWindowLimitTimeoutNs after which an active untethered subscription will be lingered.\n     * @param untetheredLingerTimeoutNs      after which a lingering untethered subscription will transition to resting.\n     * @param untetheredRestingTimeoutNs     after which a resting untethered subscription will become active again.\n     * @param timerIntervalNs                interval at which the driver will check timeouts.\n     * @throws ConfigurationException if the values are not valid.\n     */\n    public static void validateUntetheredTimeouts(\n        final long untetheredWindowLimitTimeoutNs,\n        final long untetheredLingerTimeoutNs,\n        final long untetheredRestingTimeoutNs,","sourceCodeStart":2587,"sourceCodeEnd":2623,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-driver/src/main/java/io/aeron/driver/Configuration.java#L2587-L2623","documentation":"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.","triggerScenarios":"Calling validateUnblockTimeout with aeron.client.liveness.timeout <= aeron.timer.interval, e.g. clientLivenessTimeoutNs=500ms with timerIntervalNs=1s.","commonSituations":"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.","solutions":["Increase aeron.client.liveness.timeout so it is strictly greater than aeron.timer.interval","Or decrease aeron.timer.interval so it ticks several times within the liveness timeout","Keep ordering: timerInterval < clientLivenessTimeout < publicationUnblockTimeout"],"exampleFix":"// before\nctx.timerIntervalNs(TimeUnit.SECONDS.toNanos(1));\nctx.clientLivenessTimeoutNs(TimeUnit.MILLISECONDS.toNanos(500));\n// after\nctx.timerIntervalNs(TimeUnit.MILLISECONDS.toNanos(100));\nctx.clientLivenessTimeoutNs(TimeUnit.SECONDS.toNanos(1)); // > timerInterval","handlingStrategy":"validation","validationCode":"long timer = TimeUnit.MILLISECONDS.toNanos(100);\nlong liveness = TimeUnit.SECONDS.toNanos(1);\nif (liveness <= timer) throw new IllegalStateException(\"clientLivenessTimeout must be > timerInterval\");\nio.aeron.driver.Configuration.validateUnblockTimeout(TimeUnit.SECONDS.toNanos(15), liveness, timer);","typeGuard":null,"tryCatchPattern":"try {\n    ctx.conclude();\n} catch (ConfigurationException e) {\n    if (e.getMessage().contains(\"clientLivenessTimeoutNs\")) {\n        ctx.clientLivenessTimeoutNs(ctx.timerIntervalNs() * 10);\n        ctx.conclude();\n    } else { throw e; }\n}","preventionTips":["Keep the liveness timeout at least 5-10x the timer interval","Do not raise timer interval without re-checking all dependent timeouts","Keep driver and client liveness timeout settings in sync intentionally"],"tags":["aeron","configuration","timeout","validation"],"backgroundTag":"conflicting-config-options","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}