aeron-io/aeron · critical · ActiveDriverException

Active media driver detected

Error message

Active media driver detected: {aeronDirectory}/CncFile

What it means

Thrown during driver startup when the driver directory already contains a CnC file indicating another media driver is currently live. CommonContext.isDriverActive detects a heartbeat from a live driver within the driver timeout window, so this process refuses to start a second driver on the same aeron directory.

Solutions

Stop the existing driver process (or wait for it to exit) before launching a new one.
Set a distinct aeron.dir via MediaDriver.Context().aeronDirectoryName("/tmp/aeron-<unique>") per driver instance.
If the old driver is dead but the file persists, wait driverTimeoutMs or delete the stale CnC file after verifying no driver process remains.
Catch ActiveDriverException and attach to the existing driver instead of launching a new one (use Aeron.connect against the shared directory).

Example fix

// before
MediaDriver.launch(); // collides with running driver on default dir
// after
MediaDriver.launch(new MediaDriver.Context()
    .aeronDirectoryName("/tmp/aeron-" + UUID.randomUUID()));

Defensive patterns

Strategy: validation

Validate before calling

if (CommonContext.isDriverActive(ctx.driverTimeoutMs(), System.err::println, ctx.mapExistingCncFile(s -> {}))) {
    throw new IllegalStateException("refusing to launch: driver already active on " + ctx.aeronDirectory());
}

Try / catch

try {
    mediaDriver = MediaDriver.launch(ctx);
} catch (ActiveDriverException e) {
    mediaDriver = null; // attach to existing driver instead
    aeron = Aeron.connect(new Aeron.Context().aeronDirectoryName(ctx.aeronDirectoryName()));
}

Prevention

Give every driver a unique aeronDirectoryName
Check isDriverActive before launch in shared environments
Ensure orderly shutdown hooks stop the driver before process exit
Avoid auto-restart managers relaunching faster than driverTimeoutMs

When it happens

Trigger: Launching MediaDriver.launch() (or ensureDirectoryIsRecreated during Context.conclude) while another driver process is running on the same aeron.directory; or starting a driver immediately after killing a previous one before its timeout lapsed with a stale CnC file.

Common situations: Two test processes sharing the default /dev/shm or tmp directory; supervisor auto-restart racing the old driver's shutdown; containers reusing a mounted aeron directory; forgetting a unique aeron.dir per process in tests.

Related errors

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

Appendix: source

Thrown at aeron-driver/src/main/java/io/aeron/driver/MediaDriver.java:502

    private static void ensureDirectoryIsRecreated(final Context ctx)
    {
        if (ctx.aeronDirectory().isDirectory())
        {
            if (ctx.warnIfDirectoryExists())
            {
                System.err.println("WARNING: " + ctx.aeronDirectory() + " exists");
            }

            if (!ctx.dirDeleteOnStart())
            {
                final Consumer<String> logger = ctx.warnIfDirectoryExists() ? System.err::println : (s) -> {};
                final MappedByteBuffer cncByteBuffer = ctx.mapExistingCncFile(logger);
                try
                {
                    if (CommonContext.isDriverActive(ctx.driverTimeoutMs(), logger, cncByteBuffer))
                    {
                        throw new ActiveDriverException("Active media driver detected: " +
                            new File(ctx.aeronDirectory(), CncFileDescriptor.CNC_FILE));
                    }

                    reportExistingErrors(ctx, cncByteBuffer);
                }
                finally
                {
                    BufferUtil.free(cncByteBuffer);
                }
            }

            ctx.deleteDirectory();
        }

        IoUtil.ensureDirectoryExists(ctx.aeronDirectory(), "aeron");
    }

    private static void reportExistingErrors(final Context ctx, final MappedByteBuffer cncByteBuffer)

View on GitHub (pinned to 6d60124e15)