aeron-io/aeron · critical · AeronException

Driver events adapter is invalid

Error message

Driver events adapter is invalid

What it means

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.

Solutions

1. Check the Media Driver is still running and healthy before/while the client runs
2. Restart the Aeron client (create a new Aeron instance) after driver recovery
3. Add a driver liveness check or use driver heartbeat counters to detect driver death early
4. Run the driver under a supervisor (systemd, k8s restart policy) to minimize windows of unavailability

Example fix

// before
Aeron aeron = Aeron.connect(ctx); // assumed driver immortal
// after
if (DriverTracker.isDriverAlive(ctx.aeronDirectoryName())) {
    Aeron aeron = Aeron.connect(ctx);
} else {
    restartDriverAndReconnect();
}

if (!Files.exists(Path.of(aeronDir, "driver-ready"))) { startDriverFirst(); }

catch (AeronException e) { if (e.getMessage().contains("Driver events adapter is invalid")) { client.close(); client = Aeron.connect(ctx); resubscribeAll(); } }

When it happens

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

Common situations: Media Driver killed (OOM, SIGKILL) while clients stay up; shared-memory directory removed; driver upgraded/restarted while old clients connect.

Related errors

• no response from MediaDriver within
• MediaDriver ( ) keepalive: age= ms > timeout= ms
• unexpected close of heartbeat timestamp counter
• CnC file is created but not initialised
• CnC file not created: <cncFile.getAbsolutePath()>

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

Appendix: source

Thrown at aeron-client/src/main/java/io/aeron/ClientConductor.java:1786

        }
        catch (final AgentTerminationException ex)
        {
            if (isClientApiCall(correlationId))
            {
                terminateConductor();
            }

            throw ex;
        }
        catch (final Exception ex)
        {
            if (driverEventsAdapter.isInvalid())
            {
                terminateConductor();

                if (!isClientApiCall(correlationId))
                {
                    throw new AeronException("Driver events adapter is invalid", ex);
                }
            }

            if (isClientApiCall(correlationId))
            {
                throw ex;
            }

            handleError(ex);
        }

        return workCount;
    }

    private void terminateConductor()
    {
        isTerminating = true;
        forceCloseResources();

View on GitHub (pinned to 6d60124e15)