What causes "service interval exceeded: timeout= , interval= " in aeron-io/aeron?

Keep callbacks fast: move heavy work off the conductor thread into a queue/worker

aeron-io/aeron · error · ConductorServiceTimeoutException

service interval exceeded: timeout=

Error message

service interval exceeded: timeout=<timeout>, interval=<interval>

What it means

ConductorServiceTimeoutException thrown when the interval between two successive services of the client conductor (its duty-cycle loop) exceeded the interServiceTimeoutNs. This means the application starved the conductor thread (or blocked it inside a callback) for so long the driver may have timed the client out; the conductor terminates itself to stay safe.

Solutions

Keep callbacks fast: move heavy work off the conductor thread into a queue/worker
Increase Context.interServiceTimeout if your workload legitimately pauses
Check GC settings and container CPU limits for long pauses
Never block (sleep, I/O, locks) inside Aeron client callbacks

Example fix

// before
subscription.onAvailableImage(img -> parseAndWriteToDisk(img)); // blocks conductor thread
// after
subscription.onAvailableImage(img -> workQueue.offer(img));

Defensive patterns

Strategy: try-catch

Try / catch

catch (ConductorServiceTimeoutException e) { recreateClient(); } // conductor self-terminated; a new Aeron instance is required

Prevention

Never block or do heavy work inside Aeron callbacks
Tune Context.interServiceTimeout for pause-prone environments
Watch GC pauses and container CPU throttling
Avoid debugger suspends on the conductor thread during development

When it happens

Trigger: Blocking for longer than interServiceTimeout (default 10s) inside an available-image handler or other client callback; the conductor thread descheduled (VM pause, container CPU throttling, debugger breakpoint); calling blocking operations from within callbacks.

Common situations: Long GC pauses or VM freezes; heavy work (parsing, I/O) done inside image-available callbacks on the conductor thread; cgroup CPU limits starving the thread; debuggers suspending the thread during development.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

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

Appendix: source

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

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

            workCount += checkLiveness(nowNs);
            workCount += checkLingeringResources(nowNs);
        }

        return workCount;
    }

    private void checkServiceInterval(final long nowNs)
    {
        if ((timeOfLastServiceNs + interServiceTimeoutNs) - nowNs < 0)
        {
            terminateConductor();

            throw new ConductorServiceTimeoutException(
                "service interval exceeded: timeout=" + SystemUtil.formatDuration(interServiceTimeoutNs) +
                ", interval=" + SystemUtil.formatDuration(nowNs - timeOfLastServiceNs));
        }
    }

    private int checkLiveness(final long nowNs)
    {
        if ((timeOfLastKeepAliveNs + keepAliveIntervalNs) - nowNs < 0)
        {
            final long nowMs = epochClock.time();
            final long lastKeepAliveMs = driverProxy.timeOfLastDriverKeepaliveMs();

            if (nowMs > (lastKeepAliveMs + driverTimeoutMs))
            {
                terminateConductor();

                if (Aeron.NULL_VALUE == lastKeepAliveMs)
                {

View on GitHub (pinned to 6d60124e15)