{"record":{"id":"b3c88d33e69f5cce","repo":"aeron-io/aeron","slug":"no-driver-heartbeat-detected","errorCode":null,"errorMessage":"no driver heartbeat detected","messagePattern":"no driver heartbeat detected","errorType":"exception","errorClass":"DriverTimeoutException","httpStatus":null,"severity":"error","filePath":"aeron-client/src/main/java/io/aeron/Aeron.java","lineNumber":2063,"sourceCode":"\n                if (!CncFileDescriptor.isCncFileLengthSufficient(cncMetaDataBuffer, cncByteBuffer.capacity()))\n                {\n                    BufferUtil.free(cncByteBuffer);\n                    cncByteBuffer = null;\n                    cncMetaDataBuffer = null;\n\n                    sleep(Configuration.AWAITING_IDLE_SLEEP_MS);\n                    continue;\n                }\n\n                final ManyToOneRingBuffer ringBuffer = new ManyToOneRingBuffer(\n                    CncFileDescriptor.createToDriverBuffer(cncByteBuffer, cncMetaDataBuffer));\n\n                while (0 == ringBuffer.consumerHeartbeatTime())\n                {\n                    if (clock.time() > deadlineMs)\n                    {\n                        throw new DriverTimeoutException(\"no driver heartbeat detected\");\n                    }\n\n                    sleep(Configuration.AWAITING_IDLE_SLEEP_MS);\n                }\n\n                final long timeMs = clock.time();\n                if (ringBuffer.consumerHeartbeatTime() < (timeMs - driverTimeoutMs()))\n                {\n                    if (timeMs > deadlineMs)\n                    {\n                        throw new DriverTimeoutException(\"no driver heartbeat detected\");\n                    }\n\n                    BufferUtil.free(cncByteBuffer);\n                    cncByteBuffer = null;\n                    cncMetaDataBuffer = null;\n\n                    sleep(100);","sourceCodeStart":2045,"sourceCodeEnd":2081,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-client/src/main/java/io/aeron/Aeron.java#L2045-L2081","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["Start the MediaDriver before connecting the client (or use Aeron.connect with a driver that auto-starts)","Increase the connect awaiting timeout via ctx.awaitingIdleStrategy(...) or waitAndSleep strategies to give a slow driver more time","Verify the aeron.dir points at the correct C'n' file of a running, compatible driver version","Check driver logs and shared memory permissions (e.g. /dev/shm size in containers)"],"exampleFix":"// before\nAeron aeron = Aeron.connect(); // driver not started -> DriverTimeoutException\n// after\nMediaDriver driver = MediaDriver.launch();\nAeron.Context ctx = new Aeron.Context().awaitingIdleStrategy(new BusySpinIdleStrategy());\nAeron aeron = Aeron.connect(ctx);","handlingStrategy":"try-catch","validationCode":"File cnc = new File(ctx.aeronDir(), CncFileDescriptor.CNC_FILE); if (!cnc.exists()) { mediaDriver = MediaDriver.launch(); }","typeGuard":null,"tryCatchPattern":"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; }","preventionTips":["Always start (or verify) the MediaDriver before connecting clients","Add readiness checks in orchestration so the client waits for the driver","Increase awaiting timeout for slow driver startup environments","Check /dev/shm capacity and permissions in containers"],"tags":["driver","timeout","startup","heartbeat","media-driver"],"backgroundTag":"request-timeout","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"}