{"record":{"id":"828759fcca03caed","repo":"aeron-io/aeron","slug":"failed-to-add-catchup-log-as-follower-channel","errorCode":null,"errorMessage":"failed to add catchup log as follower - ${channel}","messagePattern":"failed to add catchup log as follower - (.+?)","errorType":"exception","errorClass":"ClusterException","httpStatus":null,"severity":"error","filePath":"aeron-cluster/src/main/java/io/aeron/cluster/Election.java","lineNumber":1074,"sourceCode":"    }\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            }\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","sourceCodeStart":1056,"sourceCodeEnd":1092,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-cluster/src/main/java/io/aeron/cluster/Election.java#L1056-L1092","documentation":"ClusterException (WARN) thrown while a follower waits for its catchup log subscription to connect: the media driver reported the subscription's channel status as ERRORED. The follower could not add the catchup replay image, so the catchup cannot proceed and the election for this member fails.","triggerScenarios":"During FOLLOWER_CATCHUP_AWAIT, logSubscription.channelStatus() returns ChannelEndpointStatus.ERRORED, typically because the underlying URI/name resolution/binding of the catchup channel failed in the driver.","commonSituations":"Invalid or unreachable catchup channel addresses (multi-icast/unicast misconfiguration), driver-side errors like port already in use, network interface names wrong in cluster channel config.","solutions":["Inspect the media driver logs for the underlying channel error (e.g. bind failure, unknown host)","Fix the cluster ingress/log/replay channel endpoints in the member's config so the catchup channel resolves and binds","Check ports are free and not blocked by firewall between follower and leader","Restart the node after fixing channel config; the election will be retried"],"exampleFix":"// before\n.udpChannel(\"aeron:udp?endpoint=192.168.0.14:20000\")\n// after (correct, reachable member address)\n.udpChannel(\"aeron:udp?endpoint=192.168.0.14|20000\") // verify host:port reachable from leader","handlingStrategy":"validation","validationCode":"// pre-validate the log/catchup channel URI resolves and interface exists\nChannelUriStringBuilder b = new ChannelUriStringBuilder().media(\"udp\").endpoint(host, port);\nif (!networkInterfaceExists(interfaceOf(b.build()))) {\n    throw new IllegalArgumentException(\"catchup channel interface missing\");\n}","typeGuard":null,"tryCatchPattern":"catch (ClusterException e) {\n    if (e.getMessage().startsWith(\"failed to add catchup log\")) {\n        // check driver error log, fix channel config, restart member\n    }\n}","preventionTips":["Validate channel endpoints/interfaces in config at startup","Reserve ports to avoid conflicts","Test multicast/unicast connectivity between members before deployment"],"tags":["network","udp-channel","catchup"],"backgroundTag":"network-request-failed","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-19T12:17:13.211Z"}