aeron-io/aeron · error · DriverTimeoutException

CnC file is created but not populated…

Error message

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

What it means

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.

Solutions

1. Delete the truncated cnc.dat and restart the media driver cleanly
2. Check driver logs and system logs (OOM killer, disk-full errors)
3. Increase the client's await deadline if the machine is heavily loaded
4. Ensure adequate free disk/memory in the aeron directory

Example fix

// before
Aeron aeron = Aeron.connect(new Aeron.Context().aeronDirectoryName("/dev/shm/aeron"));
// driver crashed mid-init, tiny cnc.dat remains

// after
// rm /dev/shm/aeron/cnc.dat, restart driver, then connect
Aeron aeron = Aeron.connect(new Aeron.Context().aeronDirectoryName("/dev/shm/aeron"));

File cnc = new File(aeronDir, "cnc.dat");
if (cnc.exists() && cnc.length() < CncFileDescriptor.META_DATA_LENGTH) {
    throw new IllegalStateException("CnC file truncated/driver crashed mid-init: " + cnc.getAbsolutePath());
}

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

When it happens

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

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

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 initialised…
• 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/1aad64464c2f6843. Report an issue: GitHub.

Appendix: source

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

        {
            while (!cncFile.exists() || cncFile.length() < CncFileDescriptor.META_DATA_LENGTH)
            {
                if (clock.time() > deadlineMs)
                {
                    throw new DriverTimeoutException("CnC file not created: " + cncFile.getAbsolutePath());
                }

                sleep(Aeron.Configuration.IDLE_SLEEP_DEFAULT_MS);
            }

            try (FileChannel fileChannel = FileChannel.open(cncFile.toPath(), READ, WRITE))
            {
                final long fileSize = fileChannel.size();
                if (fileSize < CncFileDescriptor.META_DATA_LENGTH)
                {
                    if (clock.time() > deadlineMs)
                    {
                        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());

View on GitHub (pinned to 6d60124e15)