aeron-io/aeron · error · ClusterException

memberId= not found in clusterMembers

Error message

memberId=${memberId} not found in clusterMembers

What it means

This constructor path builds/updates a ClusterMember from a memberId and memberEndpoints; when memberId is not NULL_VALUE it must exist in the provided clusterMembers list. If no member with that id is present, this ClusterException is thrown.

Solutions

1. Ensure the memberId exists in the clusterMembers array you pass in
2. Update the member id after any cluster membership change
3. Pass NULL_VALUE for memberId when not targeting a specific member
4. Verify cluster membership matches the running cluster via ClusterMembersQuery/control response

Example fix

// before
new ClusterMember(clusterMembers, /*memberId=*/3, endpoints) // member 3 removed
// after
new ClusterMember(clusterMembers, /*memberId=*/0, endpoints) // use a valid id

boolean memberExists(ClusterMember[] members, int memberId) {
    if (memberId == ClusterMember.NULL_VALUE) return true;
    for (ClusterMember m : members) { if (m.id() == memberId) return true; }
    return false;
}

ClusterMember findMember(ClusterMember[] members, int id) {
    for (ClusterMember m : members) { if (m.id() == id) return m; }
    return null;
}

try {
    ClusterMember m = new ClusterMember(clusterMembers, memberId, endpoints);
} catch (ClusterException e) {
    if (e.getMessage().contains("not found in clusterMembers")) {
        log.error("memberId " + memberId + " stale; refresh cluster membership", e);
    }
}

When it happens

Trigger: Constructing a ClusterMember via this overload with a memberId that has no matching ClusterMember in the clusterMembers array (and memberId != NULL_VALUE).

Common situations: Stale member id after reconfiguring the cluster (ids changed), passing a snapshot/leader memberId from a different cluster topology, or building 'detailed events' style client configs referencing a removed member.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

• invalid member value
• empty key not allowed at index
• invalid end of key at index
• no more input found, state=
• media type is mandatory

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

Appendix: source

Thrown at aeron-cluster/src/main/java/io/aeron/cluster/ClusterMember.java:1059

     * @param clusterMembers  for the current cluster which can be null.
     * @param memberId        for this member.
     * @param memberEndpoints for this member.
     * @return the {@link ClusterMember} determined.
     */
    public static ClusterMember determineMember(
        final ClusterMember[] clusterMembers, final int memberId, final String memberEndpoints)
    {
        ClusterMember member = NULL_VALUE != memberId ? ClusterMember.findMember(clusterMembers, memberId) : null;

        if ((null == clusterMembers || 0 == clusterMembers.length) && null == member)
        {
            member = ClusterMember.parseEndpoints(NULL_VALUE, memberEndpoints);
        }
        else
        {
            if (null == member)
            {
                throw new ClusterException("memberId=" + memberId + " not found in clusterMembers");
            }

            if (!memberEndpoints.isEmpty())
            {
                ClusterMember.validateMemberEndpoints(member, memberEndpoints);
            }
        }

        return member;
    }

    /**
     * Check the member with the memberEndpoints.
     *
     * @param member          to check memberEndpoints against.
     * @param memberEndpoints to check member against.
     * @see ConsensusModule.Context#memberEndpoints()
     * @see ConsensusModule.Context#clusterMembers()

View on GitHub (pinned to 6d60124e15)