aeron-io/aeron · error · ConfigurationException

interServiceTimeoutNs=

Error message

interServiceTimeoutNs=<interServiceTimeoutNs> <= keepAliveIntervalNs=<keepAliveIntervalNs>

What it means

After connecting to the driver's C'n' file, Aeron reads the client liveness timeout from the driver and uses it as interServiceTimeoutNs. If that timeout is not strictly greater than the configured keepAliveIntervalNs, the client could be declared dead by the driver even while heartbeating, so the Context throws this ConfigurationException. It indicates an inconsistent client/keepalive configuration or a driver configured with an unusually small timeout.

Solutions

1. Lower the client keepAliveIntervalNs so it is strictly less than the driver's client liveness timeout
2. Raise the driver's aeron.client.liveness.timeout so it exceeds the client keepalive interval (requires driver restart)
3. Verify the C'n' file being connected to belongs to the driver instance you configured

Example fix

// before
ctx.keepAliveIntervalNs(TimeUnit.SECONDS.toNanos(1)); // driver liveness timeout is 500ms -> throws
// after
ctx.keepAliveIntervalNs(TimeUnit.MILLISECONDS.toNanos(100)); // must be < driver clientLivenessTimeoutNs

// after obtaining CncMetaDataBuffer: long liveness = CncFileDescriptor.clientLivenessTimeoutNs(meta); if (liveness <= ctx.keepAliveIntervalNs()) { ctx.keepAliveIntervalNs(liveness / 4); }

try { return Aeron.connect(ctx); } catch (ConfigurationException e) { if (e.getMessage().contains("interServiceTimeoutNs") && e.getMessage().contains("keepAliveIntervalNs")) { ctx.keepAliveIntervalNs(TimeUnit.MILLISECONDS.toNanos(100)); return Aeron.connect(ctx); } throw e; }

When it happens

Trigger: Connecting to a media driver whose C'n' file reports clientLivenessTimeoutNs <= the client's keepAliveIntervalNs, e.g. driver configured with a very small client liveness timeout while the client keeps the default keepAliveIntervalNs, or the client explicitly set a large keepAliveIntervalNs via ctx.keepAliveIntervalNs(...).

Common situations: Tuning a low-latency driver (short liveness timeout) without lowering the client keepalive interval; driver and client using different configuration sets; loading stale driver properties after reconfiguring the driver.

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

• MediaDriver ( ) keepalive: age= ms > timeout= ms
• startupCanvassTimeoutNs=
• newLeaderTimeoutNs must be positive or -1, but was
• publicationUnblockTimeoutNs=
• clientLivenessTimeoutNs=

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

Appendix: source

Thrown at aeron-client/src/main/java/io/aeron/Aeron.java:1232

            }

            if (null == idleStrategy)
            {
                idleStrategy = new SleepingMillisIdleStrategy(TimeUnit.NANOSECONDS.toMillis(idleSleepDurationNs));
            }

            if (null == awaitingIdleStrategy)
            {
                awaitingIdleStrategy = new SleepingMillisIdleStrategy(Configuration.AWAITING_IDLE_SLEEP_MS);
            }

            connectToDriver();
            filePageSize = driverFilePageSize(cncMetaDataBuffer);

            interServiceTimeoutNs = CncFileDescriptor.clientLivenessTimeoutNs(cncMetaDataBuffer);
            if (interServiceTimeoutNs <= keepAliveIntervalNs)
            {
                throw new ConfigurationException("interServiceTimeoutNs=" + interServiceTimeoutNs +
                    " <= keepAliveIntervalNs=" + keepAliveIntervalNs);
            }

            if (null == toDriverBuffer)
            {
                toDriverBuffer = new ManyToOneRingBuffer(
                    CncFileDescriptor.createToDriverBuffer(cncByteBuffer, cncMetaDataBuffer));
            }

            if (null == toClientBuffer)
            {
                toClientBuffer = new CopyBroadcastReceiver(new BroadcastReceiver(
                    CncFileDescriptor.createToClientsBuffer(cncByteBuffer, cncMetaDataBuffer)),
                    new ExpandableArrayBuffer(CopyBroadcastReceiver.SCRATCH_BUFFER_LENGTH));
            }

            if (countersMetaDataBuffer() == null)
            {

View on GitHub (pinned to 6d60124e15)