{"record":{"id":"f7d1760f3ea7892b","repo":"aeron-io/aeron","slug":"cnc-file-is-created-but-not-initialised-cncfile","errorCode":null,"errorMessage":"CnC file is created but not initialised: <cncFile.getAbsolutePath()>","messagePattern":"CnC file is created but not initialised: <cncFile\\.getAbsolutePath\\(\\)>","errorType":"exception","errorClass":"DriverTimeoutException","httpStatus":null,"severity":"error","filePath":"aeron-client/src/main/java/io/aeron/CommonContext.java","lineNumber":1424,"sourceCode":"                    {\n                        throw new DriverTimeoutException(\n                            \"CnC file is created but not populated: \" + cncFile.getAbsolutePath());\n                    }\n\n                    fileChannel.close();\n                    sleep(Aeron.Configuration.IDLE_SLEEP_DEFAULT_MS);\n                    continue;\n                }\n\n                final UnsafeBuffer metaDataBuffer =\n                    CncFileDescriptor.createMetaDataBuffer(fileChannel.map(READ_WRITE, 0, fileSize));\n\n                int cncVersion;\n                while (0 == (cncVersion = metaDataBuffer.getIntVolatile(CncFileDescriptor.cncVersionOffset(0))))\n                {\n                    if (clock.time() > deadlineMs)\n                    {\n                        throw new DriverTimeoutException(\"CnC file is created but not initialised: \" +\n                            cncFile.getAbsolutePath());\n                    }\n\n                    sleep(Aeron.Configuration.AWAITING_IDLE_SLEEP_MS);\n                }\n\n                CncFileDescriptor.checkVersion(cncVersion);\n                if (SemanticVersion.minor(cncVersion) < SemanticVersion.minor(CncFileDescriptor.CNC_VERSION))\n                {\n                    throw new AeronException(\"driverVersion=\" + SemanticVersion.toString(cncVersion) +\n                        \" insufficient for clientVersion=\" +\n                        SemanticVersion.toString(CncFileDescriptor.CNC_VERSION));\n                }\n\n                return metaDataBuffer;\n            }\n            catch (final NoSuchFileException | AccessDeniedException ignore)\n            {","sourceCodeStart":1406,"sourceCodeEnd":1442,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-client/src/main/java/io/aeron/CommonContext.java#L1406-L1442","documentation":"Once the CnC file is fully sized, the client spins on the volatile cncVersion field until the driver writes a non-zero version. If the version stays zero past the deadline, the driver created and sized the file but never initialised it, so a DriverTimeoutException with the CnC path is thrown.","triggerScenarios":"Awaiting a driver whose process created cnc.dat with full metadata length but crashed or hung before storing the version field, exceeding clock.time() > deadlineMs.","commonSituations":"Driver wedged during startup; two drivers racing on the same aeron.dir leaving an uninitialised file; container killed after file creation but before version store; stale cnc.dat from an aborted run.","solutions":["Delete the stale cnc.dat and restart the media driver","Investigate why the driver hangs at startup (logs, thread dumps)","Ensure only one driver uses the aeron directory (prevent racing drivers)","Raise the await deadline (deadlineMs) on slow/loaded systems"],"exampleFix":"// before\nAeron aeron = Aeron.connect(new Aeron.Context().aeronDirectoryName(\"/dev/shm/aeron\"));\n\n// after\n// remove uninitialised file, restart driver\n// rm /dev/shm/aeron/cnc.dat\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(\"created but not initialised\")) { deleteStaleCnc(); restartDriver(); retryConnect(); } else { throw e; } }","preventionTips":["Ensure only one media driver owns the aeron directory","Remove uninitialised cnc.dat after aborted driver runs","Investigate driver startup hangs with logs/thread dumps","Allow a generous driverTimeoutMs on loaded machines"],"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"}