aeron-io/aeron · error · DriverTimeoutException

CnC file is created but not initialised…

Error message

CnC file is created but not initialised: <cncFile.getAbsolutePath()>

What it means

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.

Solutions

1. Delete the stale cnc.dat and restart the media driver
2. Investigate why the driver hangs at startup (logs, thread dumps)
3. Ensure only one driver uses the aeron directory (prevent racing drivers)
4. Raise the await deadline (deadlineMs) on slow/loaded systems

Example fix

// before
Aeron aeron = Aeron.connect(new Aeron.Context().aeronDirectoryName("/dev/shm/aeron"));

// after
// remove uninitialised file, restart driver
// rm /dev/shm/aeron/cnc.dat
Aeron aeron = Aeron.connect(new Aeron.Context()
    .aeronDirectoryName("/dev/shm/aeron")
    .driverTimeoutMs(30_000));

try { Aeron aeron = Aeron.connect(ctx); } catch (DriverTimeoutException e) { if (e.getMessage().contains("created but not initialised")) { deleteStaleCnc(); restartDriver(); retryConnect(); } else { throw e; } }

When it happens

Trigger: 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.

Common situations: 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.

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

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

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

Appendix: source

Thrown at aeron-client/src/main/java/io/aeron/CommonContext.java:1424

                    {
                        throw new DriverTimeoutException(
                            "CnC file is created but not populated: " + cncFile.getAbsolutePath());
                    }

                    fileChannel.close();
                    sleep(Aeron.Configuration.IDLE_SLEEP_DEFAULT_MS);
                    continue;
                }

                final UnsafeBuffer metaDataBuffer =
                    CncFileDescriptor.createMetaDataBuffer(fileChannel.map(READ_WRITE, 0, fileSize));

                int cncVersion;
                while (0 == (cncVersion = metaDataBuffer.getIntVolatile(CncFileDescriptor.cncVersionOffset(0))))
                {
                    if (clock.time() > deadlineMs)
                    {
                        throw new DriverTimeoutException("CnC file is created but not initialised: " +
                            cncFile.getAbsolutePath());
                    }

                    sleep(Aeron.Configuration.AWAITING_IDLE_SLEEP_MS);
                }

                CncFileDescriptor.checkVersion(cncVersion);
                if (SemanticVersion.minor(cncVersion) < SemanticVersion.minor(CncFileDescriptor.CNC_VERSION))
                {
                    throw new AeronException("driverVersion=" + SemanticVersion.toString(cncVersion) +
                        " insufficient for clientVersion=" +
                        SemanticVersion.toString(CncFileDescriptor.CNC_VERSION));
                }

                return metaDataBuffer;
            }
            catch (final NoSuchFileException | AccessDeniedException ignore)
            {

View on GitHub (pinned to 6d60124e15)