{"record":{"id":"a183b437b20092ec","repo":"aeron-io/aeron","slug":"failed-to-add-new-leader-ingress-publication-leadermemberid","errorCode":null,"errorMessage":"failed to add new leader ingress publication (leaderMemberId=, leadershipTermId=, channel=, streamId=) within ","messagePattern":"failed to add new leader ingress publication \\(leaderMemberId=, leadershipTermId=, channel=, streamId=\\) within ","errorType":"exception","errorClass":"TimeoutException","httpStatus":null,"severity":"error","filePath":"aeron-cluster/src/main/java/io/aeron/cluster/client/AeronCluster.java","lineNumber":790,"sourceCode":"                if (null != publication)\n                {\n                    return publication;\n                }\n            }\n            catch (final RegistrationException ex)\n            {\n                registrationId = NULL_VALUE;\n                if (ErrorCode.RESOURCE_TEMPORARILY_UNAVAILABLE != ex.errorCode())\n                {\n                    throw ex;\n                }\n            }\n\n            idleStrategy.idle(ctx.runAgentInvokers());\n        }\n        while (nanoClock.nanoTime() < deadlineNs);\n\n        throw new TimeoutException(\"failed to add new leader ingress publication (leaderMemberId=\" + leaderMemberId +\n            \", leadershipTermId=\" + leadershipTermId + \", channel=\" + channel + \", streamId=\" + streamId +\n            \") within \" + SystemUtil.formatDuration(ctx.messageTimeoutNs()));\n    }\n\n    static long asyncAddIngressPublication(final Context ctx, final String channel, final int streamId)\n    {\n        if (ctx.isIngressExclusive())\n        {\n            return ctx.aeron().asyncAddExclusivePublication(channel, streamId);\n        }\n        else\n        {\n            return ctx.aeron().asyncAddPublication(channel, streamId);\n        }\n    }\n\n    static Publication getIngressPublication(final Context ctx, final long registrationId)\n    {","sourceCodeStart":772,"sourceCodeEnd":808,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-cluster/src/main/java/io/aeron/cluster/client/AeronCluster.java#L772-L808","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the ingressEndpoints configuration contains a reachable address for the new leaderMemberId.","Increase Context.messageTimeoutNs() to allow more time for publication establishment on slow networks.","Check network connectivity/firewall to the leader's ingress endpoint (telnet/curl the host:port).","Ensure the client's Aeron agent is being invoked (runAgentInvokers) so async publication additions can complete.","Catch TimeoutException and re-attempt connect/onNewLeader after the network recovers."],"exampleFix":"// before\nctx.messageTimeoutNs(TimeUnit.SECONDS.toNanos(5));\n// after\nctx.messageTimeoutNs(TimeUnit.SECONDS.toNanos(30)); // allow failover publication establishment","handlingStrategy":"retry","validationCode":"if (!isHostReachable(endpointForLeader(leaderMemberId))) { waitAndRetryBeforeOnNewLeader(); }","typeGuard":null,"tryCatchPattern":"try { cluster.onNewLeader(...); } catch (TimeoutException e) { backoff(); retryOrReconnectCluster(); }","preventionTips":["Keep ingressEndpoints accurate and reachable for every member.","Set messageTimeoutNs generously relative to network RTT.","Monitor leader failover events and publication establishment latency."],"tags":["cluster","timeout","network","failover","ingress"],"backgroundTag":"request-timeout","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}