{"record":{"id":"1aad64464c2f6843","repo":"aeron-io/aeron","slug":"cnc-file-is-created-but-not-populated-cncfile","errorCode":null,"errorMessage":"CnC file is created but not populated: <cncFile.getAbsolutePath()>","messagePattern":"CnC file is created but not populated: <cncFile\\.getAbsolutePath\\(\\)>","errorType":"exception","errorClass":"DriverTimeoutException","httpStatus":null,"severity":"error","filePath":"aeron-client/src/main/java/io/aeron/CommonContext.java","lineNumber":1407,"sourceCode":"        {\n            while (!cncFile.exists() || cncFile.length() < CncFileDescriptor.META_DATA_LENGTH)\n            {\n                if (clock.time() > deadlineMs)\n                {\n                    throw new DriverTimeoutException(\"CnC file not created: \" + cncFile.getAbsolutePath());\n                }\n\n                sleep(Aeron.Configuration.IDLE_SLEEP_DEFAULT_MS);\n            }\n\n            try (FileChannel fileChannel = FileChannel.open(cncFile.toPath(), READ, WRITE))\n            {\n                final long fileSize = fileChannel.size();\n                if (fileSize < CncFileDescriptor.META_DATA_LENGTH)\n                {\n                    if (clock.time() > deadlineMs)\n                    {\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());","sourceCodeStart":1389,"sourceCodeEnd":1425,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-client/src/main/java/io/aeron/CommonContext.java#L1389-L1425","documentation":"After the CnC file exists, the client opens it and checks that its size is at least CncFileDescriptor.META_DATA_LENGTH. If the file remains smaller than the required metadata length past the deadline, the driver created the file but never populated it, and a DriverTimeoutException is thrown.","triggerScenarios":"A driver process created cnc.dat but crashed or was suspended before writing the full metadata section, while a client awaited the driver past its deadline (clock.time() > deadlineMs).","commonSituations":"Driver killed mid-initialisation (kill -9, OOM killer); disk full so the file could not be extended; driver process paused (container CPU throttling) longer than the client's deadline.","solutions":["Delete the truncated cnc.dat and restart the media driver cleanly","Check driver logs and system logs (OOM killer, disk-full errors)","Increase the client's await deadline if the machine is heavily loaded","Ensure adequate free disk/memory in the aeron directory"],"exampleFix":"// before\nAeron aeron = Aeron.connect(new Aeron.Context().aeronDirectoryName(\"/dev/shm/aeron\"));\n// driver crashed mid-init, tiny cnc.dat remains\n\n// after\n// rm /dev/shm/aeron/cnc.dat, restart driver, then connect\nAeron aeron = Aeron.connect(new Aeron.Context().aeronDirectoryName(\"/dev/shm/aeron\"));","handlingStrategy":"retry","validationCode":"File cnc = new File(aeronDir, \"cnc.dat\");\nif (cnc.exists() && cnc.length() < CncFileDescriptor.META_DATA_LENGTH) {\n    throw new IllegalStateException(\"CnC file truncated/driver crashed mid-init: \" + cnc.getAbsolutePath());\n}","typeGuard":null,"tryCatchPattern":"try { Aeron aeron = Aeron.connect(ctx); } catch (DriverTimeoutException e) { if (e.getMessage().contains(\"not populated\")) { deleteStaleCnc(); restartDriver(); retryConnect(); } else { throw e; } }","preventionTips":["Clean up cnc.dat after kill -9 / OOM kills of the driver","Ensure free disk space in the aeron directory","Avoid CPU-starving the driver during startup (container limits)"],"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"}