aeron-io/aeron · error · AeronException

unexpected interrupt

Error message

unexpected interrupt

What it means

Thrown when the thread waiting for a reply from the Media Driver is interrupted unexpectedly. The conductor treats an interrupt during a synchronous await as fatal: it terminates the conductor and raises AeronException('unexpected interrupt'). Aeron uses interrupts as a shutdown signal, not a control mechanism.

Solutions

1. Avoid blocking Aeron calls on threads that get interrupted; use async (non-blocking) variants and poll for the future later
2. Shut down executors gracefully (awaitTermination) before interrupting threads that use Aeron
3. If shutdown is intended, catch the exception and treat conductor termination as expected
4. Move Aeron setup off request/interruptible paths into dedicated lifecycle threads

Example fix

// before
Future<?> f = pool.submit(() -> aeron.addPublication(channel, stream));
f.cancel(true); // interrupts mid-await
// after
Future<?> f = pool.submit(() -> aeron.addPublication(channel, stream));
pool.shutdown();
pool.awaitTermination(10, TimeUnit.SECONDS); // no interrupt mid-await

try { aeron.addPublication(ch, stream); } catch (AeronException e) { if (e.getMessage().contains("unexpected interrupt")) { handleShutdown(); } else { throw e; } }

When it happens

Trigger: Another thread calls Thread.interrupt() (e.g. executor.shutdownNow(), Thread.stop-style teardown, or Future.cancel(true)) on the application thread blocked in awaitResponse for an addPublication/addSubscription/other correlated command.

Common situations: Calling blocking Aeron add APIs inside a task pool that is cancelled with shutdownNow(); test frameworks timing out and interrupting threads; container/JVM shutdown hooks interrupting worker threads.

Related errors

• client is closed
• client is closed
• counter id is not allocated, state
• Aeron client is terminating
• reentrant calls not permitted during callbacks

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

Appendix: source

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

            service(correlationId);

            if (driverEventsAdapter.receivedCorrelationId() == correlationId)
            {
                stashedChannelByRegistrationId.remove(correlationId);
                final RegistrationException ex = driverException;
                if (null != ex)
                {
                    driverException = null;
                    throw ex;
                }

                return;
            }

            if (Thread.currentThread().isInterrupted())
            {
                terminateConductor();
                throw new AeronException("unexpected interrupt");
            }
        }
        while (deadlineNs - nanoClock.nanoTime() > 0);

        throw new DriverTimeoutException("no response from MediaDriver within " +
            SystemUtil.formatDuration(driverTimeoutNs));
    }

    private int checkTimeouts(final long nowNs)
    {
        int workCount = 0;

        if ((timeOfLastServiceNs + idleSleepDurationNs) - nowNs < 0)
        {
            checkServiceInterval(nowNs);
            timeOfLastServiceNs = nowNs;

            workCount += checkLiveness(nowNs);

View on GitHub (pinned to 6d60124e15)