aeron-io/aeron · error · TimeoutException

failed to add new leader ingress publication…

Error message

failed to add new leader ingress publication (leaderMemberId=, leadershipTermId=, channel=, streamId=) within

What it means

addNewLeaderIngressPublication asynchronously adds an ExclusivePublication for the new leader's ingress endpoint and waits within a deadline of ctx.messageTimeoutNs(). If the publication is not added (position still not connected / add not completed) before the deadline, the library throws TimeoutException describing the leader member, leadership term, channel and stream id.

Solutions

  1. Verify the ingressEndpoints configuration contains a reachable address for the new leaderMemberId.
  2. Increase Context.messageTimeoutNs() to allow more time for publication establishment on slow networks.
  3. Check network connectivity/firewall to the leader's ingress endpoint (telnet/curl the host:port).
  4. Ensure the client's Aeron agent is being invoked (runAgentInvokers) so async publication additions can complete.
  5. Catch TimeoutException and re-attempt connect/onNewLeader after the network recovers.

Example fix

// before
ctx.messageTimeoutNs(TimeUnit.SECONDS.toNanos(5));
// after
ctx.messageTimeoutNs(TimeUnit.SECONDS.toNanos(30)); // allow failover publication establishment
Defensive patterns

Strategy: retry

Validate before calling

if (!isHostReachable(endpointForLeader(leaderMemberId))) { waitAndRetryBeforeOnNewLeader(); }

Try / catch

try { cluster.onNewLeader(...); } catch (TimeoutException e) { backoff(); retryOrReconnectCluster(); }

Prevention

When it happens

Trigger: Calling onNewLeader() or updateMemberEndpoints() when the new leader's ingress publication cannot be established within messageTimeoutNs — leader unreachable on its ingress endpoint, wrong ingressEndpoints config, network partition, or a client thread not running agents/idling properly.

Common situations: Leader failover where the new leader's ingress address is firewalled or misconfigured in ingressEndpoints; message timeout set too low for slow networks; client not invoking its Aeron agent (runAgentInvokers) frequently enough.

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.

Related errors

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

Appendix: source

Thrown at aeron-cluster/src/main/java/io/aeron/cluster/client/AeronCluster.java:790

                if (null != publication)
                {
                    return publication;
                }
            }
            catch (final RegistrationException ex)
            {
                registrationId = NULL_VALUE;
                if (ErrorCode.RESOURCE_TEMPORARILY_UNAVAILABLE != ex.errorCode())
                {
                    throw ex;
                }
            }

            idleStrategy.idle(ctx.runAgentInvokers());
        }
        while (nanoClock.nanoTime() < deadlineNs);

        throw new TimeoutException("failed to add new leader ingress publication (leaderMemberId=" + leaderMemberId +
            ", leadershipTermId=" + leadershipTermId + ", channel=" + channel + ", streamId=" + streamId +
            ") within " + SystemUtil.formatDuration(ctx.messageTimeoutNs()));
    }

    static long asyncAddIngressPublication(final Context ctx, final String channel, final int streamId)
    {
        if (ctx.isIngressExclusive())
        {
            return ctx.aeron().asyncAddExclusivePublication(channel, streamId);
        }
        else
        {
            return ctx.aeron().asyncAddPublication(channel, streamId);
        }
    }

    static Publication getIngressPublication(final Context ctx, final long registrationId)
    {

View on GitHub (pinned to 6d60124e15)