aeron-io/aeron · critical · AgentTerminationException

interrupted

Error message

interrupted

What it means

ClusteredServiceAgent.doIdleWork checks Thread.currentThread().isInterrupted() and throws AgentTerminationException("interrupted") if the duty-cycle thread has been interrupted. This is the agent's cooperative shutdown hook: interruption means the JVM or owner wants the cluster agent to stop, so it terminates the agent rather than continuing to idle.

Solutions

1. If shutdown is intended, let the agent terminate: use ClusteredServiceContainer/Cluster's proper close/stop methods instead of raw interrupt.
2. Do not run other interrupt-sensitive work on the cluster duty-cycle thread or interrupt it incidentally (e.g. from a shared ExecutorService.shutdownNow).
3. If interruption was accidental, restart the cluster container; the exception is intentionally terminal.

Example fix

// before
executor.shutdownNow(); // interrupts the cluster agent thread
// after
cluster.close(); // graceful stop, then
executor.shutdown();

// java: before interrupting a thread hosting a cluster agent
if (thread.getName().contains("cluster") || agentThread == thread) {
    throw new IllegalStateException("use the container's close()/stop(), not interrupt()");
}

try {
    clusterContainer.start();
} catch (AgentTerminationException e) {
    // thread was interrupted during shutdown; treat as a deliberate stop and re-run
    // clean up and restart only if the interruption was accidental
}

When it happens

Trigger: Another thread calls interrupt() on the cluster agent's duty-cycle thread — typically during shutdown, Thread.interrupt from a supervisor, or an ExecutorService.shutdownNow().

Common situations: Application shutdown hooks interrupting the cluster thread; container/executor shutdownNow(); misuse of interrupt() to signal work cancellation while a cluster agent is running on that thread.

Related errors

• unexpected interrupt
• Archive.Context.threadingMode(ArchiveThreadingMode.INVOKER)…
• unexpected Aeron close
• unexpected driver close
• name + " cannot be negative: value=" + value

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

Appendix: source

Thrown at aeron-cluster/src/main/java/io/aeron/cluster/service/ClusteredServiceAgent.java:436

    {
        idleStrategy.idle();
        doIdleWork();
    }

    public void idle(final int workCount)
    {
        idleStrategy.idle(workCount);
        if (workCount <= 0)
        {
            doIdleWork();
        }
    }

    private void doIdleWork()
    {
        if (Thread.currentThread().isInterrupted())
        {
            throw new AgentTerminationException("interrupted");
        }

        final long nowNs = nanoClock.nanoTime();

        checkForClockTick(nowNs);

        if (isServiceActive)
        {
            invokeBackgroundWork(nowNs);
        }
    }

    void onJoinLog(
        final long logPosition,
        final long maxLogPosition,
        final int memberId,
        final int logSessionId,
        final int logStreamId,

View on GitHub (pinned to 6d60124e15)