{"record":{"id":"0e85a4def49a79b2","repo":"alibaba/nacos","slug":"failed-to-install-jraft-authentication-interceptor","errorCode":null,"errorMessage":"Failed to install JRaft authentication interceptor","messagePattern":"Failed to install JRaft authentication interceptor","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"critical","filePath":"core/src/main/java/com/alibaba/nacos/core/distributed/raft/utils/JRaftUtils.java","lineNumber":91,"sourceCode":"            ReadRequest.getDefaultInstance());\n        raftRpcFactory.registerProtobufSerializer(Response.class.getName(),\n            Response.getDefaultInstance());\n        \n        MarshallerRegistry registry = raftRpcFactory.getMarshallerRegistry();\n        registry.registerResponseInstance(Log.class.getName(), Response.getDefaultInstance());\n        registry.registerResponseInstance(GetRequest.class.getName(),\n            Response.getDefaultInstance());\n        \n        registry.registerResponseInstance(WriteRequest.class.getName(),\n            Response.getDefaultInstance());\n        registry.registerResponseInstance(ReadRequest.class.getName(),\n            Response.getDefaultInstance());\n        \n        final RpcServer rpcServer = raftRpcFactory.createRpcServer(peerId.getEndpoint());\n        boolean interceptorAdded = ((GrpcServer) rpcServer).addServerInterceptor(\n            new NacosJRaftServerInterceptor(jRaftAuthUpgradeCoordinator));\n        if (!interceptorAdded) {\n            throw new IllegalStateException(\"Failed to install JRaft authentication interceptor\");\n        }\n        RaftRpcServerFactory.addRaftRequestProcessors(rpcServer, RaftExecutor.getRaftCoreExecutor(),\n            RaftExecutor.getRaftCliServiceExecutor());\n        \n        rpcServer.registerProcessor(new NacosWriteRequestProcessor(server));\n        rpcServer.registerProcessor(new NacosReadRequestProcessor(server));\n        \n        return rpcServer;\n    }\n    \n    public static final void initDirectory(String parentPath, String groupName, NodeOptions copy) {\n        final String logUri = Paths.get(parentPath, groupName, \"log\").toString();\n        final String snapshotUri = Paths.get(parentPath, groupName, \"snapshot\").toString();\n        final String metaDataUri = Paths.get(parentPath, groupName, \"meta-data\").toString();\n        \n        // Initialize the raft file storage path for different services\n        try {\n            DiskUtils.forceMkdir(new File(logUri));","sourceCodeStart":73,"sourceCodeEnd":109,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/core/src/main/java/com/alibaba/nacos/core/distributed/raft/utils/JRaftUtils.java#L73-L109","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    jRaftServer.start();\n} catch (JRaftException | IllegalStateException e) {\n    // interceptor install failed — verify JRaft version compatibility\n}","preventionTips":["Do not override the bundled JRaft/gRPC dependency versions.","Add interceptors before rpcServer.init() in any customization."],"tags":["raft","jraft","grpc","interceptor","auth","startup","cp-protocol"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}