{"record":{"id":"7658d94179134497","repo":"aeron-io/aeron","slug":"failed-to-join-catchup-log","errorCode":null,"errorMessage":"failed to join catchup log","messagePattern":"failed to join catchup log","errorType":"exception","errorClass":"TimeoutException","httpStatus":null,"severity":"warning","filePath":"aeron-cluster/src/main/java/io/aeron/cluster/Election.java","lineNumber":1083,"sourceCode":"            verifyLogJoinPosition(\"followerCatchupAwait\", image.joinPosition());\n            if (consensusModuleAgent.tryJoinLogAsFollower(image, isLeaderStartup, nowNs))\n            {\n                state(FOLLOWER_CATCHUP, nowNs, \"\");\n                workCount++;\n            }\n            else if (ChannelEndpointStatus.ERRORED == logSubscription.channelStatus())\n            {\n                final String message = \"failed to add catchup log as follower - \" + logSubscription.channel();\n                throw new ClusterException(message, AeronException.Category.WARN);\n            }\n            else if (nowNs >= (timeOfLastStateChangeNs + ctx.leaderHeartbeatTimeoutNs()))\n            {\n                throw new TimeoutException(\"failed to join catchup log as follower\", AeronException.Category.WARN);\n            }\n        }\n        else if (nowNs >= (timeOfLastStateChangeNs + ctx.leaderHeartbeatTimeoutNs()))\n        {\n            throw new TimeoutException(\"failed to join catchup log\", AeronException.Category.WARN);\n        }\n\n        return workCount;\n    }\n\n    private int followerCatchup(final long nowNs)\n    {\n        int workCount = consensusModuleAgent.catchupPoll(notifiedCommitPosition, nowNs);\n\n        if (null == consensusModuleAgent.liveLogDestination() &&\n            consensusModuleAgent.isCatchupNearLive(max(catchupJoinPosition, notifiedCommitPosition)))\n        {\n            addLiveLogDestination();\n            workCount++;\n        }\n\n        final long position = ctx.commitPositionCounter().getPlain();\n        if (position >= catchupJoinPosition &&","sourceCodeStart":1065,"sourceCodeEnd":1101,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-cluster/src/main/java/io/aeron/cluster/Election.java#L1065-L1101","documentation":"TimeoutException (WARN) thrown when the follower fails to reach the point of joining the catchup log at all: before any subscription progress is observed, the leaderHeartbeatTimeoutNs window expires. It is the outer, earlier failure mode of the catchup join compared to \"failed to join catchup log as follower\".","triggerScenarios":"followerCatchupInit in an early branch: neither the catchup position send nor a subscription state change happened within timeOfLastStateChangeNs + ctx.leaderHeartbeatTimeoutNs().","commonSituations":"Leader election stalled because candidate leader never responded; total network outage; misconfigured replay channel so no traffic ever flows; watchdog pauses on the follower.","solutions":["Check whether a valid leader exists at all (cluster may be stuck canvassing); inspect election logs on all members","Fix member channel configuration so replay traffic can flow","Increase leaderHeartbeatTimeoutNs if the environment is legitimately slow","Restart the node to re-enter canvass and retry the election"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// ensure a quorum of members is up before expecting elections to complete\nif (liveMembers() < quorumSize()) {\n    LOG.warn(\"no quorum; catchup joins will time out\");\n}","typeGuard":null,"tryCatchPattern":"catch (TimeoutException e) {\n    // outer catchup timeout; verify leader existence then re-enter election\n}","preventionTips":["Run at least quorum+1 members for fault tolerance","Monitor cluster canvass state","Keep replay channels configured identically on all members"],"tags":["timeout","election","catchup"],"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"}