{"record":{"id":"734fe69dcb2a71f3","repo":"aeron-io/aeron","slug":"cnc-file-is-created-but-not-initialised","errorCode":null,"errorMessage":"CnC file is created but not initialised","messagePattern":"CnC file is created but not initialised","errorType":"exception","errorClass":"DriverTimeoutException","httpStatus":null,"severity":"error","filePath":"aeron-client/src/main/java/io/aeron/CommonContext.java","lineNumber":1111,"sourceCode":"     * @return true if a driver is active or false if not.\n     */\n    public static boolean isDriverActive(\n        final long driverTimeoutMs, final Consumer<String> logger, final ByteBuffer cncByteBuffer)\n    {\n        if (null == cncByteBuffer)\n        {\n            return false;\n        }\n\n        final UnsafeBuffer cncMetaDataBuffer = CncFileDescriptor.createMetaDataBuffer(cncByteBuffer);\n\n        final long startTimeMs = System.currentTimeMillis();\n        int cncVersion;\n        while (0 == (cncVersion = cncMetaDataBuffer.getIntVolatile(CncFileDescriptor.cncVersionOffset(0))))\n        {\n            if (System.currentTimeMillis() > (startTimeMs + driverTimeoutMs))\n            {\n                throw new DriverTimeoutException(\"CnC file is created but not initialised\");\n            }\n\n            sleep(1);\n        }\n\n        CncFileDescriptor.checkVersion(cncVersion);\n\n        final ManyToOneRingBuffer toDriverBuffer = new ManyToOneRingBuffer(\n            CncFileDescriptor.createToDriverBuffer(cncByteBuffer, cncMetaDataBuffer));\n\n        final long timestampMs = toDriverBuffer.consumerHeartbeatTime();\n        final long nowMs = System.currentTimeMillis();\n        final long timestampAgeMs = nowMs - timestampMs;\n\n        logger.accept(\"INFO: Aeron toDriver consumer heartbeat age is (ms): \" + timestampAgeMs);\n\n        return timestampAgeMs <= driverTimeoutMs;\n    }","sourceCodeStart":1093,"sourceCodeEnd":1129,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-client/src/main/java/io/aeron/CommonContext.java#L1093-L1129","documentation":"When a client attaches to a driver via the CnC file, it waits up to driverTimeoutMs for the CnC version field to become non-zero. If the file exists and has non-zero length but the version is never written, the driver that created it died or stalled before initialisation, so a DriverTimeoutException is thrown.","triggerScenarios":"Calling Aeron.connect() (or CommonContext operations that map the CnC file) while a driver process is creating but has not initialised cnc.dat, and the driver crashes or hangs during startup for longer than driverTimeoutMs.","commonSituations":"Driver crashed mid-startup leaving a zero-version CnC file; starting the client simultaneously with the driver on a slow machine; a hung driver process; leftover partially-created CnC file after a kill -9.","solutions":["Delete the stale cnc.dat from the aeron directory and restart the media driver","Check the driver's logs for a crash or hang during startup","Increase driverTimeoutMs on the client context if driver startup is legitimately slow","Ensure the driver process has permission to finish writing the CnC file (disk, memory)"],"exampleFix":"// before\nAeron aeron = Aeron.connect(new Aeron.Context().aeronDirectoryName(\"/dev/shm/aeron\"));\n\n// after\n// restart driver first, or raise timeout:\nAeron aeron = Aeron.connect(new Aeron.Context()\n    .aeronDirectoryName(\"/dev/shm/aeron\")\n    .driverTimeoutMs(30_000));","handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"try { Aeron aeron = Aeron.connect(ctx); } catch (DriverTimeoutException e) { if (e.getMessage().contains(\"not initialised\")) { deleteStaleCncAndRestartDriver(); retryConnect(); } else { throw e; } }","preventionTips":["Start the driver and wait for it to be ready before connecting clients","Delete leftover cnc.dat after abnormal driver termination","Set driverTimeoutMs appropriately for your startup latency","Monitor driver startup health in orchestration (readiness probes)"],"tags":["aeron","driver","timeout","cnc-file"],"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"}