{"record":{"id":"cd1fc6fc7fc9757c","repo":"aeron-io/aeron","slug":"active-media-driver-detected-aerondirectory-cncfile","errorCode":null,"errorMessage":"Active media driver detected: {aeronDirectory}/CncFile","messagePattern":"Active media driver detected: (.+?)/CncFile","errorType":"exception","errorClass":"ActiveDriverException","httpStatus":null,"severity":"critical","filePath":"aeron-driver/src/main/java/io/aeron/driver/MediaDriver.java","lineNumber":502,"sourceCode":"\n    private static void ensureDirectoryIsRecreated(final Context ctx)\n    {\n        if (ctx.aeronDirectory().isDirectory())\n        {\n            if (ctx.warnIfDirectoryExists())\n            {\n                System.err.println(\"WARNING: \" + ctx.aeronDirectory() + \" exists\");\n            }\n\n            if (!ctx.dirDeleteOnStart())\n            {\n                final Consumer<String> logger = ctx.warnIfDirectoryExists() ? System.err::println : (s) -> {};\n                final MappedByteBuffer cncByteBuffer = ctx.mapExistingCncFile(logger);\n                try\n                {\n                    if (CommonContext.isDriverActive(ctx.driverTimeoutMs(), logger, cncByteBuffer))\n                    {\n                        throw new ActiveDriverException(\"Active media driver detected: \" +\n                            new File(ctx.aeronDirectory(), CncFileDescriptor.CNC_FILE));\n                    }\n\n                    reportExistingErrors(ctx, cncByteBuffer);\n                }\n                finally\n                {\n                    BufferUtil.free(cncByteBuffer);\n                }\n            }\n\n            ctx.deleteDirectory();\n        }\n\n        IoUtil.ensureDirectoryExists(ctx.aeronDirectory(), \"aeron\");\n    }\n\n    private static void reportExistingErrors(final Context ctx, final MappedByteBuffer cncByteBuffer)","sourceCodeStart":484,"sourceCodeEnd":520,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-driver/src/main/java/io/aeron/driver/MediaDriver.java#L484-L520","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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)."],"exampleFix":"// before\nMediaDriver.launch(); // collides with running driver on default dir\n// after\nMediaDriver.launch(new MediaDriver.Context()\n    .aeronDirectoryName(\"/tmp/aeron-\" + UUID.randomUUID()));","handlingStrategy":"validation","validationCode":"if (CommonContext.isDriverActive(ctx.driverTimeoutMs(), System.err::println, ctx.mapExistingCncFile(s -> {}))) {\n    throw new IllegalStateException(\"refusing to launch: driver already active on \" + ctx.aeronDirectory());\n}","typeGuard":null,"tryCatchPattern":"try {\n    mediaDriver = MediaDriver.launch(ctx);\n} catch (ActiveDriverException e) {\n    mediaDriver = null; // attach to existing driver instead\n    aeron = Aeron.connect(new Aeron.Context().aeronDirectoryName(ctx.aeronDirectoryName()));\n}","preventionTips":["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"],"tags":["aeron","driver","startup","shared-directory"],"backgroundTag":"address-already-in-use","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-19T12:17:13.211Z"}