{"record":{"id":"ec570f4034e06bcc","repo":"aeron-io/aeron","slug":"failed-to-send-catchup-position","errorCode":null,"errorMessage":"failed to send catchup position","messagePattern":"failed to send catchup position","errorType":"exception","errorClass":"TimeoutException","httpStatus":null,"severity":"warning","filePath":"aeron-cluster/src/main/java/io/aeron/cluster/Election.java","lineNumber":1052,"sourceCode":"            {\n                final int i = resolvedEndpoint.lastIndexOf(':');\n                catchupEndpoint = endpoint.substring(0, endpoint.length() - 2) + resolvedEndpoint.substring(i);\n            }\n        }\n        else\n        {\n            catchupEndpoint = endpoint;\n        }\n\n        if (null != catchupEndpoint && sendCatchupPosition(catchupEndpoint))\n        {\n            timeOfLastUpdateNs = nowNs;\n            consensusModuleAgent.catchupInitiated(nowNs);\n            state(FOLLOWER_CATCHUP_AWAIT, nowNs, \"\");\n        }\n        else if (nowNs >= (timeOfLastStateChangeNs + ctx.leaderHeartbeatTimeoutNs()))\n        {\n            throw new TimeoutException(\"failed to send catchup position\", AeronException.Category.WARN);\n        }\n\n        return 1;\n    }\n\n    private int followerCatchupAwait(final long nowNs)\n    {\n        int workCount = 0;\n\n        final Image image = logSubscription.imageBySessionId(logSessionId);\n        if (null != image)\n        {\n            verifyLogJoinPosition(\"followerCatchupAwait\", image.joinPosition());\n            if (consensusModuleAgent.tryJoinLogAsFollower(image, isLeaderStartup, nowNs))\n            {\n                state(FOLLOWER_CATCHUP, nowNs, \"\");\n                workCount++;\n            }","sourceCodeStart":1034,"sourceCodeEnd":1070,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-cluster/src/main/java/io/aeron/cluster/Election.java#L1034-L1070","documentation":"TimeoutException (WARN) thrown in Election.followerCatchupInit when the follower fails to successfully send its catchup position request to the (candidate) leader within ctx.leaderHeartbeatTimeoutNs. The follower needs to replay missing log entries but could not deliver the request to the leader's replayPublication before the deadline.","triggerScenarios":"Follower in FOLLOWER_CATCHUP_INIT tries to send a catchup position to the leader each doWork tick; if the send keeps failing (publication not connected) and timeOfLastStateChangeNs + leaderHeartbeatTimeoutNs elapses, this is thrown.","commonSituations":"Leader went down mid-election; network partition; leader replay publication not yet connected because the leader is overloaded; leaderHeartbeatTimeoutNs too small when starting large clusters.","solutions":["Check connectivity to the candidate leader on the cluster/replay channels","Increase ctx.leaderHeartbeatTimeoutNs() to give publications time to connect","Verify the leader is still up; retry the election by restarting the node or letting the timeout re-canvas","Check that leader's replay service is not saturated by other catchup requests"],"exampleFix":"// before\n.clusterContext(ctx -> ctx.leaderHeartbeatTimeoutNs(TimeUnit.SECONDS.toNanos(10)))\n// after\n.clusterContext(ctx -> ctx.leaderHeartbeatTimeoutNs(TimeUnit.SECONDS.toNanos(30)))","handlingStrategy":"retry","validationCode":"// verify leader reachability before/at cluster startup\nif (!isHostReachable(leaderHost, replayPort)) {\n    LOG.warn(\"leader replay endpoint unreachable; catchup will likely time out\");\n}","typeGuard":null,"tryCatchPattern":"catch (TimeoutException e) {\n    // follower re-canvas: retry is built-in; surface metric catchup_send_timeouts++\n}","preventionTips":["Set leaderHeartbeatTimeoutNs >= 10s for production","Ensure replay ports open on all members","Monitor publication connection status in driver logs"],"tags":["timeout","log-catchup","election"],"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"}