aeron-io/aeron · error · DriverTimeoutException

no driver heartbeat detected

Error message

no driver heartbeat detected

What it means

While awaiting a usable connection to the media driver, Aeron waits for the to-driver ring buffer's consumerHeartbeatTime to become non-zero, proving the driver is alive and consuming. If no heartbeat appears before the deadline (awaiting idle timeout), it throws DriverTimeoutException('no driver heartbeat detected'), meaning the driver process did not start consuming commands in time (or is not running at all).

Solutions

1. Start the MediaDriver before connecting the client (or use Aeron.connect with a driver that auto-starts)
2. Increase the connect awaiting timeout via ctx.awaitingIdleStrategy(...) or waitAndSleep strategies to give a slow driver more time
3. Verify the aeron.dir points at the correct C'n' file of a running, compatible driver version
4. Check driver logs and shared memory permissions (e.g. /dev/shm size in containers)

Example fix

// before
Aeron aeron = Aeron.connect(); // driver not started -> DriverTimeoutException
// after
MediaDriver driver = MediaDriver.launch();
Aeron.Context ctx = new Aeron.Context().awaitingIdleStrategy(new BusySpinIdleStrategy());
Aeron aeron = Aeron.connect(ctx);

File cnc = new File(ctx.aeronDir(), CncFileDescriptor.CNC_FILE); if (!cnc.exists()) { mediaDriver = MediaDriver.launch(); }

try { Aeron aeron = Aeron.connect(ctx); } catch (DriverTimeoutException e) { if (e.getMessage().contains("no driver heartbeat")) { /* start/restart driver, clear stale Cn' file, retry with backoff */ } else throw e; }

When it happens

Trigger: Calling Aeron.connect(ctx) when no media driver is running; driver present but too slow to start within the awaiting timeout (ctx.awaitingIdleStrategy / awaiting timeout exceeded); connecting to a C'n' file of a crashed or stale driver; driver version mismatch leaving the C'n' file unreadable.

Common situations: Forgetting to start the MediaDriver before the client; driver failing at startup after creating the C'n' file; container orchestration starting the client before the driver is ready; shared-memory/disk permission issues preventing the client from seeing driver updates.

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.

Related errors

• no response from MediaDriver within
• MediaDriver ( ) keepalive: age= ms > timeout= ms
• CnC file is created but not initialised
• CnC file not created: <cncFile.getAbsolutePath()>
• CnC file is created but not populated…

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

Appendix: source

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

                if (!CncFileDescriptor.isCncFileLengthSufficient(cncMetaDataBuffer, cncByteBuffer.capacity()))
                {
                    BufferUtil.free(cncByteBuffer);
                    cncByteBuffer = null;
                    cncMetaDataBuffer = null;

                    sleep(Configuration.AWAITING_IDLE_SLEEP_MS);
                    continue;
                }

                final ManyToOneRingBuffer ringBuffer = new ManyToOneRingBuffer(
                    CncFileDescriptor.createToDriverBuffer(cncByteBuffer, cncMetaDataBuffer));

                while (0 == ringBuffer.consumerHeartbeatTime())
                {
                    if (clock.time() > deadlineMs)
                    {
                        throw new DriverTimeoutException("no driver heartbeat detected");
                    }

                    sleep(Configuration.AWAITING_IDLE_SLEEP_MS);
                }

                final long timeMs = clock.time();
                if (ringBuffer.consumerHeartbeatTime() < (timeMs - driverTimeoutMs()))
                {
                    if (timeMs > deadlineMs)
                    {
                        throw new DriverTimeoutException("no driver heartbeat detected");
                    }

                    BufferUtil.free(cncByteBuffer);
                    cncByteBuffer = null;
                    cncMetaDataBuffer = null;

                    sleep(100);

View on GitHub (pinned to 6d60124e15)