Membership change clarification

[Sahith Nallapareddy via user <us...@ratis.apache.org>]

Hello,

I am new to Apache Ratis and Raft and have been learning a lot through
trial and error. One scenario I am dealing with is membership change.
I see in the documentation it specifies

Start the new peer N3 with EMPTY group.

        RaftServer N3 = RaftServer.newBuilder()
            .setGroup(RaftGroup.emptygroup())
            .setProperties(properties)
            .setServerId(n3id)
            .setStateMachine(userStateMachine)
            .build();
        N3.start()

The group is RaftGroup.emptyGroup())

The example code conflicts with this as well

https://github.com/apache/ratis/blob/master/ratis-examples/src/main/java/org/apache/ratis/examples/membership/server/RaftCluster.java#L80

        // New peer always start with an empty group.
        RaftGroup group = RaftGroup.valueOf(GROUP_ID);

which is a raft group with matching group id but no peers.

So when we are saying empty group, do we mean a RaftGroup with no
peers, and does the group id matter? Should it match the group id that
the peer is joining?

Thanks,

Sahith

Re: Membership change clarification

[Tsz Wo Sze <sz...@apache.org>]

Hi Sahith,

Thanks for trying Ratis!

> So when we are saying empty group, do we mean a RaftGroup with no peers,
and does the group id matter?  Should it match the group id that
the peer is joining?

Yes, empty group means a group with a group id and an empty peer list.  The
group id must be the same as the group the peer is joining.  Then, the new
server will wait for the existing leader after it has started.  When the
leader sends appendEntries to the new server.   It will get the up-to-date
peer list.

If we specify an non-empty group, the new servers may start leader
elections and cause problems.

Please feel free to let us know if you have any other questions.

Tsz-Wo




On Tue, Feb 24, 2026 at 12:16 PM Sahith Nallapareddy via user <
user@ratis.apache.org> wrote:

> Hello,
>
> I am new to Apache Ratis and Raft and have been learning a lot through
> trial and error. One scenario I am dealing with is membership change.
> I see in the documentation it specifies
>
> Start the new peer N3 with EMPTY group.
>
>         RaftServer N3 = RaftServer.newBuilder()
>             .setGroup(RaftGroup.emptygroup())
>             .setProperties(properties)
>             .setServerId(n3id)
>             .setStateMachine(userStateMachine)
>             .build();
>         N3.start()
>
> The group is RaftGroup.emptyGroup())
>
> The example code conflicts with this as well
>
>
> https://github.com/apache/ratis/blob/master/ratis-examples/src/main/java/org/apache/ratis/examples/membership/server/RaftCluster.java#L80
>
>         // New peer always start with an empty group.
>         RaftGroup group = RaftGroup.valueOf(GROUP_ID);
>
> which is a raft group with matching group id but no peers.
>
> So when we are saying empty group, do we mean a RaftGroup with no
> peers, and does the group id matter? Should it match the group id that
> the peer is joining?
>
> Thanks,
>
> Sahith
>