aeron-io/aeron · error · DriverTimeoutException

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

Error message

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

What it means

When awaiting a driver, the client polls for the CnC file to exist and be at least META_DATA_LENGTH bytes. If the file never appears (or stays too small) within the deadline, a DriverTimeoutException naming the expected CnC path is thrown.

Solutions

  1. Start the Aeron media driver before connecting the client
  2. Verify the client's aeronDirectoryName matches the driver's (aeron.dir)
  3. Check filesystem permissions on the aeron directory so the driver can create cnc.dat
  4. Increase the await deadline (clock-based deadlineMs) if driver startup is slow

Example fix

// before
Aeron aeron = Aeron.connect(); // no driver running at default dir

// after
MediaDriver.launch(new MediaDriver.Context().aeronDirectoryName("/dev/shm/aeron"));
Aeron aeron = Aeron.connect(new Aeron.Context().aeronDirectoryName("/dev/shm/aeron"));
Defensive patterns

Strategy: retry

Validate before calling

File cnc = new File(aeronDir, "cnc.dat");
if (!cnc.exists()) {
    throw new IllegalStateException("No Aeron driver CnC file at " + cnc.getAbsolutePath() + " - start the media driver first");
}

Try / catch

try { Aeron aeron = Aeron.connect(ctx); } catch (DriverTimeoutException e) { if (e.getMessage().startsWith("CnC file not created")) { startDriverOrFixDir(); retryConnect(); } else { throw e; } }

Prevention

When it happens

Trigger: Calling Aeron.connect() (or CommonContext.awaitDriver) with useDriverActiveCheck/conductorTickNanos await logic when no media driver is running at cncFile's directory, and the file is not created before the deadline.

Common situations: Forgot to start the media driver before connecting the client; driver started in a different aeron.dir than the client; driver failed to start due to permissions on the directory; typo in aeronDirectoryName.

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/568b7a44b1b508e0. Report an issue: GitHub.

Appendix: source

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

    }

    static int driverFilePageSize(final DirectBuffer metadata)
    {
        final int pageSize = CncFileDescriptor.filePageSize(metadata);
        return 0 != pageSize ? pageSize : LogBufferDescriptor.PAGE_MIN_SIZE;
    }

    @SuppressWarnings("try")
    static UnsafeBuffer awaitCncFileCreation(
        final File cncFile, final EpochClock clock, final long deadlineMs)
    {
        while (true)
        {
            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);

View on GitHub (pinned to 6d60124e15)