{"record":{"id":"ac42113fc0667b3a","repo":"aeron-io/aeron","slug":"driver-events-adapter-is-invalid","errorCode":null,"errorMessage":"Driver events adapter is invalid","messagePattern":"Driver events adapter is invalid","errorType":"exception","errorClass":"AeronException","httpStatus":null,"severity":"critical","filePath":"aeron-client/src/main/java/io/aeron/ClientConductor.java","lineNumber":1786,"sourceCode":"        }\n        catch (final AgentTerminationException ex)\n        {\n            if (isClientApiCall(correlationId))\n            {\n                terminateConductor();\n            }\n\n            throw ex;\n        }\n        catch (final Exception ex)\n        {\n            if (driverEventsAdapter.isInvalid())\n            {\n                terminateConductor();\n\n                if (!isClientApiCall(correlationId))\n                {\n                    throw new AeronException(\"Driver events adapter is invalid\", ex);\n                }\n            }\n\n            if (isClientApiCall(correlationId))\n            {\n                throw ex;\n            }\n\n            handleError(ex);\n        }\n\n        return workCount;\n    }\n\n    private void terminateConductor()\n    {\n        isTerminating = true;\n        forceCloseResources();","sourceCodeStart":1768,"sourceCodeEnd":1804,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-client/src/main/java/io/aeron/ClientConductor.java#L1768-L1804","documentation":"When an exception occurs while processing driver events, the conductor checks whether the driver events adapter has become invalid (connection to the driver's command queue lost). If so it terminates the conductor; if the failure did not originate from a client API call it surfaces as 'Driver events adapter is invalid'. This indicates the client lost its communication channel to the Media Driver.","triggerScenarios":"The driver's to-client command queue ring buffer reports an invalid state (driver shut down, buffer corrupted, or driver process killed) while the client conductor polls it; a driver crash mid-session.","commonSituations":"Media Driver killed (OOM, SIGKILL) while clients stay up; shared-memory directory removed; driver upgraded/restarted while old clients connect.","solutions":["Check the Media Driver is still running and healthy before/while the client runs","Restart the Aeron client (create a new Aeron instance) after driver recovery","Add a driver liveness check or use driver heartbeat counters to detect driver death early","Run the driver under a supervisor (systemd, k8s restart policy) to minimize windows of unavailability"],"exampleFix":"// before\nAeron aeron = Aeron.connect(ctx); // assumed driver immortal\n// after\nif (DriverTracker.isDriverAlive(ctx.aeronDirectoryName())) {\n    Aeron aeron = Aeron.connect(ctx);\n} else {\n    restartDriverAndReconnect();\n}","handlingStrategy":"retry","validationCode":"if (!Files.exists(Path.of(aeronDir, \"driver-ready\"))) { startDriverFirst(); }","typeGuard":null,"tryCatchPattern":"catch (AeronException e) { if (e.getMessage().contains(\"Driver events adapter is invalid\")) { client.close(); client = Aeron.connect(ctx); resubscribeAll(); } }","preventionTips":["Supervise the Media Driver process and restart it on death","Watch driver heartbeat counters to detect death proactively","Recreate the Aeron client after any driver restart"],"tags":["aeron","driver","ipc","process-lifecycle"],"backgroundTag":"broken-pipe","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}