aeron-io/aeron · error · DriverTimeoutException

CnC file is created but not initialised

Error message

CnC file is created but not initialised

What it means

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.

Solutions

  1. Delete the stale cnc.dat from the aeron directory and restart the media driver
  2. Check the driver's logs for a crash or hang during startup
  3. Increase driverTimeoutMs on the client context if driver startup is legitimately slow
  4. Ensure the driver process has permission to finish writing the CnC file (disk, memory)

Example fix

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

// after
// restart driver first, or raise timeout:
Aeron aeron = Aeron.connect(new Aeron.Context()
    .aeronDirectoryName("/dev/shm/aeron")
    .driverTimeoutMs(30_000));
Defensive patterns

Strategy: retry

Try / catch

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

Prevention

When it happens

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

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

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

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

Appendix: source

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

     * @return true if a driver is active or false if not.
     */
    public static boolean isDriverActive(
        final long driverTimeoutMs, final Consumer<String> logger, final ByteBuffer cncByteBuffer)
    {
        if (null == cncByteBuffer)
        {
            return false;
        }

        final UnsafeBuffer cncMetaDataBuffer = CncFileDescriptor.createMetaDataBuffer(cncByteBuffer);

        final long startTimeMs = System.currentTimeMillis();
        int cncVersion;
        while (0 == (cncVersion = cncMetaDataBuffer.getIntVolatile(CncFileDescriptor.cncVersionOffset(0))))
        {
            if (System.currentTimeMillis() > (startTimeMs + driverTimeoutMs))
            {
                throw new DriverTimeoutException("CnC file is created but not initialised");
            }

            sleep(1);
        }

        CncFileDescriptor.checkVersion(cncVersion);

        final ManyToOneRingBuffer toDriverBuffer = new ManyToOneRingBuffer(
            CncFileDescriptor.createToDriverBuffer(cncByteBuffer, cncMetaDataBuffer));

        final long timestampMs = toDriverBuffer.consumerHeartbeatTime();
        final long nowMs = System.currentTimeMillis();
        final long timestampAgeMs = nowMs - timestampMs;

        logger.accept("INFO: Aeron toDriver consumer heartbeat age is (ms): " + timestampAgeMs);

        return timestampAgeMs <= driverTimeoutMs;
    }

View on GitHub (pinned to 6d60124e15)