alibaba/nacos · critical · IllegalStateException

Failed to install JRaft authentication interceptor

Error message

Failed to install JRaft authentication interceptor

What it means

Thrown by JRaftUtils.initRpcServer when GrpcServer.addServerInterceptor(NacosJRaftServerInterceptor) returns false, meaning the authentication gRPC interceptor could not be added to the JRaft RPC server. This is an IllegalStateException raised during raft server construction (part of JRaftServer.start), preventing CP protocol startup.

Source

Thrown at core/src/main/java/com/alibaba/nacos/core/distributed/raft/utils/JRaftUtils.java:91

            ReadRequest.getDefaultInstance());
        raftRpcFactory.registerProtobufSerializer(Response.class.getName(),
            Response.getDefaultInstance());
        
        MarshallerRegistry registry = raftRpcFactory.getMarshallerRegistry();
        registry.registerResponseInstance(Log.class.getName(), Response.getDefaultInstance());
        registry.registerResponseInstance(GetRequest.class.getName(),
            Response.getDefaultInstance());
        
        registry.registerResponseInstance(WriteRequest.class.getName(),
            Response.getDefaultInstance());
        registry.registerResponseInstance(ReadRequest.class.getName(),
            Response.getDefaultInstance());
        
        final RpcServer rpcServer = raftRpcFactory.createRpcServer(peerId.getEndpoint());
        boolean interceptorAdded = ((GrpcServer) rpcServer).addServerInterceptor(
            new NacosJRaftServerInterceptor(jRaftAuthUpgradeCoordinator));
        if (!interceptorAdded) {
            throw new IllegalStateException("Failed to install JRaft authentication interceptor");
        }
        RaftRpcServerFactory.addRaftRequestProcessors(rpcServer, RaftExecutor.getRaftCoreExecutor(),
            RaftExecutor.getRaftCliServiceExecutor());
        
        rpcServer.registerProcessor(new NacosWriteRequestProcessor(server));
        rpcServer.registerProcessor(new NacosReadRequestProcessor(server));
        
        return rpcServer;
    }
    
    public static final void initDirectory(String parentPath, String groupName, NodeOptions copy) {
        final String logUri = Paths.get(parentPath, groupName, "log").toString();
        final String snapshotUri = Paths.get(parentPath, groupName, "snapshot").toString();
        final String metaDataUri = Paths.get(parentPath, groupName, "meta-data").toString();
        
        // Initialize the raft file storage path for different services
        try {
            DiskUtils.forceMkdir(new File(logUri));

View on GitHub (pinned to 9b989acdf1)

Solutions

Check the JRaftException/cause logged by JRaftServer.start for the precise reason addServerInterceptor failed.
Ensure the bundled JRaft version matches what Nacos expects (do not override the transitive JRaft/gRPC deps).
If you are customizing raft auth, verify the interceptor is added before any rpcServer.init() call.
Fall back to a known-good Nacos distribution version if this appears after an upgrade.

Defensive patterns

Strategy: try-catch

Try / catch

try {
    jRaftServer.start();
} catch (JRaftException | IllegalStateException e) {
    // interceptor install failed — verify JRaft version compatibility
}

Prevention

Do not override the bundled JRaft/gRPC dependency versions.
Add interceptors before rpcServer.init() in any customization.

When it happens

Trigger: The underlying SOFA-JRaft GrpcServer rejects interceptor registration — typically because interceptors must be added before the server is initialized, or because the JRaft/gRPC version in use changed the addServerInterceptor contract/return value.

Common situations: A JRaft library version upgrade that altered interceptor registration semantics; a code path that initializes the rpc server before calling initRpcServer; an incompatibility between the Nacos auth-upgrade coordinator and the bundled JRaft version.

Understand the failure class

Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

AI-assisted analysis of alibaba/nacos@9b989acdf1 (2026-08-14). Data as JSON: /api/errors/0e85a4def49a79b2. Report an issue: GitHub.