What causes "MediaDriver ( ) keepalive: age= ms > timeout= ms" in aeron-io/aeron?

Investigate why the driver hung (thread dump, GC logs) and fix or restart it

aeron-io/aeron · error · DriverTimeoutException

MediaDriver ( ) keepalive: age= ms > timeout= ms

Error message

MediaDriver (<aeronDirectoryName>) keepalive: age=<age>ms > timeout=<timeout>ms

What it means

DriverTimeoutException thrown when the client's keepalive check finds the driver's heartbeat timestamp is older than driverTimeoutMs even though the counter exists. The driver periodically updates its C'n'C heartbeat counter; if it stops updating for the timeout period the client assumes the driver is wedged (not cleanly shutdown) and terminates.

Solutions

Investigate why the driver hung (thread dump, GC logs) and fix or restart it
Increase Context.driverTimeoutMs if timeouts are marginal (e.g. only slightly over limit)
Run driver and client on hosts not subject to suspend/migration, or tolerate reconnect logic
Ensure the driver has enough CPU to run its housekeeping agent

Example fix

// before
Aeron aeron = Aeron.connect(new Aeron.Context().driverTimeoutMs(5_000)); // marginal on loaded host
// after
Aeron aeron = Aeron.connect(new Aeron.Context().driverTimeoutMs(30_000));

Defensive patterns

Strategy: retry

Validate before calling

long ageMs = System.currentTimeMillis() - lastKnownDriverHeartbeatMs; if (ageMs > driverTimeoutMs * 0.8) { probeDriverHealth(); }

Try / catch

catch (DriverTimeoutException e) { if (e.getMessage().contains("keepalive")) { restartClientAndOptionallyDriver(); } }

Prevention

Monitor the driver heartbeat counter and alert before the timeout elapses
Raise driverTimeoutMs on hosts prone to pauses (VMs, CI, laptops)
Keep driver CPU housekeeping unstarved

When it happens

Trigger: Media Driver process alive but hung (blocked I/O, deadlock, severe GC); machine suspended/resumed; driver on a heavily oversubscribed CPU so keepalive updates are late relative to a small driverTimeoutMs.

Common situations: Laptop sleep/VM migration freezing the driver past the timeout; driver thread starvation with very small driverTimeout; NFS/slow disk stalling the driver's housekeeping.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

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

Related errors

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

Appendix: source

Thrown at aeron-client/src/main/java/io/aeron/ClientConductor.java:1897

    private int checkLiveness(final long nowNs)
    {
        if ((timeOfLastKeepAliveNs + keepAliveIntervalNs) - nowNs < 0)
        {
            final long nowMs = epochClock.time();
            final long lastKeepAliveMs = driverProxy.timeOfLastDriverKeepaliveMs();

            if (nowMs > (lastKeepAliveMs + driverTimeoutMs))
            {
                terminateConductor();

                if (Aeron.NULL_VALUE == lastKeepAliveMs)
                {
                    throw new DriverTimeoutException(
                        "MediaDriver (" + aeron.context().aeronDirectoryName() + ") has been shutdown");
                }

                throw new DriverTimeoutException(
                    "MediaDriver (" + aeron.context().aeronDirectoryName() + ") keepalive: age=" +
                        (nowMs - lastKeepAliveMs) + "ms > timeout=" + driverTimeoutMs + "ms");
            }

            if (null == heartbeatTimestamp)
            {
                final int counterId = HeartbeatTimestamp.findCounterIdByRegistrationId(
                    countersReader, HEARTBEAT_TYPE_ID, ctx.clientId());

                if (NULL_COUNTER_ID != counterId)
                {
                    try
                    {
                        heartbeatTimestamp = new AtomicCounter(counterValuesBuffer, counterId);
                        heartbeatTimestamp.setRelease(nowMs);
                        appendToLabel(
                            countersReader.metaDataBuffer(),
                            counterId,

View on GitHub (pinned to 6d60124e15)