Thank you Tsz Wo for your prompt response.
I have raised a PR to make the documentation clearer.
https://github.com/apache/ratis/pull/1379/changes
Please take a look.
Also a small followup question, is the below code the recommended way to
get the list of followers / listeners in the *follower* nodes?
```
Division division = server.getDivision(raftGroupId);
RaftGroup raftGroup = division.getGroup();
List<RaftPeer> followers = division.getRaftConf()
.getAllPeers(RaftPeerRole.FOLLOWER)
.stream()
.toList();
List<RaftPeer> listeners = division.getRaftConf()
.getAllPeers(RaftPeerRole.LISTENER)
.stream()
.toList();
```
Regards,
Snehasish
On Thu, 12 Mar 2026 at 07:37, Tsz Wo Sze <[email protected]> wrote:
> > GroupMismatchException: n4: group-ABB3109A44C2 not found.
>
> I guess you might not have started n4 with group-ABB3109A44C2. We should
> start n4 with group-ABB3109A44C2 and an empty list of peers.
>
> Tsz-Wo
>
>
> On Wed, Mar 11, 2026 at 4:43 AM Snehasish Roy <[email protected]>
> wrote:
>
> > Hi everyone,
> >
> > I was following the documentation (
> >
> >
> https://jojochuang.github.io/ratis-site/docs/developer-guide/membership-change/#adding-a-new-server
> > )
> > for adding a new server to an existing group but faced an error.
> > These are the steps I followed
> >
> > 1. Started three servers n1, n2 and n3 with a hardcoded groupID
> > ABB3109A44C2
> > 2. Started fourth server n4 with empty group and no peer information.
> > 3. Issued a setConfiguration on n2 (the leader instance) with n1,n2,n3,n4
> > in the peer list, but faced an error citing GroupMismatchException.
> >
> > Did I miss some step? Kindly advise.
> >
> > n2 logs
> > ```
> > INFO [2026-03-11 16:47:35,651] [n2-server-thread1]
> [RaftServer$Division]:
> > n2@group-ABB3109A44C2: receive setConfiguration
> > SetConfigurationRequest:client-26207F9175D5->n2@group-ABB3109A44C2,
> cid=1,
> > seq=null, RW, null, SET_UNCONDITIONALLY, servers:[n1|0.0.0.0:9000, n2|
> > 0.0.0.0:9001, n3|0.0.0.0:9002, n4|0.0.0.0:9003], listeners:[]
> > INFO [2026-03-11 16:47:35,652] [n2-server-thread1]
> [RaftServer$Division]:
> > n2@group-ABB3109A44C2-LeaderStateImpl: startSetConfiguration
> > SetConfigurationRequest:client-26207F9175D5->n2@group-ABB3109A44C2,
> cid=1,
> > seq=null, RW, null, SET_UNCONDITIONALLY, servers:[n1|0.0.0.0:9000, n2|
> > 0.0.0.0:9001, n3|0.0.0.0:9002, n4|0.0.0.0:9003], listeners:[]
> > INFO [2026-03-11 16:47:35,655]
> > [n2@group-ABB3109A44C2->n4-GrpcLogAppender-LogAppenderDaemon]
> > [FollowerInfo]: Follower n2@group-ABB3109A44C2->n4 acknowledged
> installing
> > snapshot
> > INFO [2026-03-11 16:47:35,655]
> > [n2@group-ABB3109A44C2->n4-GrpcLogAppender-LogAppenderDaemon]
> > [GrpcServerProtocolClient]: Build channel for n4|0.0.0.0:9003
> > WARN [2026-03-11 16:47:35,887] [grpc-default-executor-5]
> > [GrpcLogAppender]: n2@group-ABB3109A44C2->n4-AppendLogResponseHandler:
> > Failed appendEntries
> > org.apache.ratis.protocol.exceptions.GroupMismatchException: n4:
> > group-ABB3109A44C2 not found.
> > at
> >
> >
> org.apache.ratis.server.impl.RaftServerProxy$ImplMap.get(RaftServerProxy.java:161)
> > at
> >
> >
> org.apache.ratis.server.impl.RaftServerProxy.getImplFuture(RaftServerProxy.java:373)
> > at
> >
> >
> org.apache.ratis.server.impl.RaftServerProxy.appendEntriesAsync(RaftServerProxy.java:653)
> > at
> >
> >
> org.apache.ratis.grpc.server.GrpcServerProtocolService$1.process(GrpcServerProtocolService.java:248)
> > at
> >
> >
> org.apache.ratis.grpc.server.GrpcServerProtocolService$1.process(GrpcServerProtocolService.java:245)
> > at
> >
> >
> org.apache.ratis.grpc.server.GrpcServerProtocolService$ServerRequestStreamObserver.onNext(GrpcServerProtocolService.java:152)
> > at
> >
> >
> org.apache.ratis.thirdparty.io.grpc.stub.ServerCalls$StreamingServerCallHandler$StreamingServerCallListener.onMessage(ServerCalls.java:262)
> > at
> >
> >
> org.apache.ratis.thirdparty.io.grpc.internal.ServerCallImpl$ServerStreamListenerImpl.messagesAvailableInternal(ServerCallImpl.java:334)
> > at
> >
> >
> org.apache.ratis.thirdparty.io.grpc.internal.ServerCallImpl$ServerStreamListenerImpl.messagesAvailable(ServerCallImpl.java:319)
> > at
> >
> >
> org.apache.ratis.thirdparty.io.grpc.internal.ServerImpl$JumpToApplicationThreadServerStreamListener$1MessagesAvailable.runInContext(ServerImpl.java:834)
> > at
> >
> >
> org.apache.ratis.thirdparty.io.grpc.internal.ContextRunnable.run(ContextRunnable.java:37)
> > at
> >
> >
> org.apache.ratis.thirdparty.io.grpc.internal.SerializingExecutor.run(SerializingExecutor.java:133)
> > at
> >
> >
> java.base/java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1136)
> > at
> >
> >
> java.base/java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:635)
> > at java.base/java.lang.Thread.run(Thread.java:840)
> > INFO [2026-03-11 16:47:35,888] [grpc-default-executor-5] [LogAppender]:
> > Decrease nextIndex to 0
> > INFO [2026-03-11 16:47:35,888] [grpc-default-executor-5] [LogAppender]:
> > Decrease nextIndex to 0
> > INFO [2026-03-11 16:47:35,888] [grpc-default-executor-5] [FollowerInfo]:
> > n2@group-ABB3109A44C2->n4: computeNextIndex nextIndex:
> > updateUnconditionally 1 -> 0
> > ....
> > ```
> >
> > n4 logs
> > ```
> > WARN [2026-03-11 16:47:35,866] [grpc-default-executor-0]
> > [GrpcServerProtocolService]: n4: Failed APPEND_ENTRIES request
> > n2->n4#1-t1,previous=<PROTO_DEFAULT>,leaderCommit=0,initializing?
> > true,entries: size=1, first=(t:1, i:0),
> > CONFIGURATIONENTRY(current:id:"n1"address:"0.0.0.0:9000
> > "startupRole:FOLLOWER,
> > id:"n2"address:"0.0.0.0:9001"startupRole:FOLLOWER, id:"n3"address:"
> > 0.0.0.0:9002"startupRole:FOLLOWER, old:)
> > java.util.concurrent.CompletionException:
> > org.apache.ratis.protocol.exceptions.GroupMismatchException: n4:
> > group-ABB3109A44C2 not found.
> > at
> >
> >
> java.base/java.util.concurrent.CompletableFuture.encodeThrowable(CompletableFuture.java:332)
> > at
> >
> >
> java.base/java.util.concurrent.CompletableFuture.uniComposeStage(CompletableFuture.java:1177)
> > at
> >
> >
> java.base/java.util.concurrent.CompletableFuture.thenCompose(CompletableFuture.java:2309)
> > at
> >
> >
> org.apache.ratis.server.impl.RaftServerProxy.appendEntriesAsync(RaftServerProxy.java:654)
> > at
> >
> >
> org.apache.ratis.grpc.server.GrpcServerProtocolService$1.process(GrpcServerProtocolService.java:248)
> > at
> >
> >
> org.apache.ratis.grpc.server.GrpcServerProtocolService$1.process(GrpcServerProtocolService.java:245)
> > at
> >
> >
> org.apache.ratis.grpc.server.GrpcServerProtocolService$ServerRequestStreamObserver.onNext(GrpcServerProtocolService.java:152)
> > at
> >
> >
> org.apache.ratis.thirdparty.io.grpc.stub.ServerCalls$StreamingServerCallHandler$StreamingServerCallListener.onMessage(ServerCalls.java:262)
> > at
> >
> >
> org.apache.ratis.thirdparty.io.grpc.internal.ServerCallImpl$ServerStreamListenerImpl.messagesAvailableInternal(ServerCallImpl.java:334)
> > at
> >
> >
> org.apache.ratis.thirdparty.io.grpc.internal.ServerCallImpl$ServerStreamListenerImpl.messagesAvailable(ServerCallImpl.java:319)
> > at
> >
> >
> org.apache.ratis.thirdparty.io.grpc.internal.ServerImpl$JumpToApplicationThreadServerStreamListener$1MessagesAvailable.runInContext(ServerImpl.java:834)
> > at
> >
> >
> org.apache.ratis.thirdparty.io.grpc.internal.ContextRunnable.run(ContextRunnable.java:37)
> > at
> >
> >
> org.apache.ratis.thirdparty.io.grpc.internal.SerializingExecutor.run(SerializingExecutor.java:133)
> > at
> >
> >
> java.base/java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1136)
> > at
> >
> >
> java.base/java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:635)
> > at java.base/java.lang.Thread.run(Thread.java:840)
> > Caused by: org.apache.ratis.protocol.exceptions.GroupMismatchException:
> n4:
> > group-ABB3109A44C2 not found.
> > at
> >
> >
> org.apache.ratis.server.impl.RaftServerProxy$ImplMap.get(RaftServerProxy.java:161)
> > at
> >
> >
> org.apache.ratis.server.impl.RaftServerProxy.getImplFuture(RaftServerProxy.java:373)
> > at
> >
> >
> org.apache.ratis.server.impl.RaftServerProxy.appendEntriesAsync(RaftServerProxy.java:653)
> > ... 12 common frames omitted
> > ```
> >
> > Regards,
> > Snehasish
> >
>
