{"record":{"id":"619c26821719ea13","repo":"alibaba/spring-ai-alibaba","slug":"no-available-endpoint-found-for-service-servicen","errorCode":null,"errorMessage":"No available endpoint found for service: <serviceName>","messagePattern":"No available endpoint found for service: <serviceName>","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"spring-boot-starters/spring-ai-alibaba-starter-config-nacos/src/main/java/com/alibaba/cloud/ai/agent/nacos/tools/NacosMcpGatewayToolCallback.java","lineNumber":469,"sourceCode":"\t\t\t\treturn \"Error: Unsupported protocol \" + protocol;\n\t\t\t}\n\t\t}\n\t\tcatch (Exception e) {\n\t\t\tlogger.error(\"[call] Unexpected error occurred\", e);\n\t\t\treturn \"Error: \" + e.getMessage();\n\t\t}\n\t}\n\n\t/**\n\t * 处理MCP流式协议的工具调用 (mcp-sse, mcp-streamable)\n\t */\n\tprivate String handleMcpStreamProtocol(Map<String, Object> args, McpServerRemoteServiceConfig remoteServerConfig,\n\t\t\tString protocol) throws NacosException {\n\t\tMcpServiceRef serviceRef = remoteServerConfig.getServiceRef();\n\t\tif (serviceRef != null) {\n\t\t\tMcpEndpointInfo mcpEndpointInfo = nacosMcpOperationService.selectEndpoint(serviceRef);\n\t\t\tif (mcpEndpointInfo == null) {\n\t\t\t\tthrow new RuntimeException(\"No available endpoint found for service: \" + serviceRef.getServiceName());\n\t\t\t}\n\n\t\t\tlogger.info(\"[handleMcpStreamProtocol] Tool callback instance: {}\", JacksonUtils.toJson(mcpEndpointInfo));\n\t\t\tString exportPath = remoteServerConfig.getExportPath();\n\n\t\t\t// 构建基础URL，根据协议类型调整\n\t\t\tString transportProtocol = StringUtils.hasText(serviceRef.getTransportProtocol()) ? serviceRef.getTransportProtocol() : \"http\";\n\t\t\tStringBuilder baseUrl;\n\t\t\tif (\"mcp-sse\".equalsIgnoreCase(protocol)) {\n\t\t\t\tbaseUrl = new StringBuilder(transportProtocol + \"://\" + mcpEndpointInfo.getAddress() + \":\" + mcpEndpointInfo.getPort());\n\t\t\t}\n\t\t\telse {\n\t\t\t\t// mcp-streamable 或其他协议\n\t\t\t\tbaseUrl = new StringBuilder(transportProtocol + \"://\" + mcpEndpointInfo.getAddress() + \":\" + mcpEndpointInfo.getPort());\n\t\t\t}\n\n\t\t\tlogger.info(\"[handleMcpStreamProtocol] Processing {} protocol with args: {} and baseUrl: {}\", protocol,\n\t\t\t\t\targs, baseUrl.toString());","sourceCodeStart":451,"sourceCodeEnd":487,"githubUrl":"https://github.com/alibaba/spring-ai-alibaba/blob/f82da0b50f35744c13968191be2b1cd2452ef550/spring-boot-starters/spring-ai-alibaba-starter-config-nacos/src/main/java/com/alibaba/cloud/ai/agent/nacos/tools/NacosMcpGatewayToolCallback.java#L451-L487","documentation":"handleMcpStreamProtocol asks Nacos (nacosMcpOperationService.selectEndpoint) to resolve an MCP service reference to a live endpoint. When Nacos returns null — no healthy/registered instance matches the serviceRef — the callback throws a RuntimeException naming the service, since there is no address to build the SSE/streamable URL from.","triggerScenarios":"call() -> handleMcpStreamProtocol with a valid serviceRef, but selectEndpoint(serviceRef) returns null: no instance registered under that service name, all instances unhealthy/disabled, or wrong namespace/group in the McpServiceRef.","commonSituations":"The MCP server backing the tool is not started or has been deregistered from Nacos; namespace/group mismatch between the gateway and the MCP server; the endpoint was published to a different Nacos cluster; network partition prevents endpoint discovery.","solutions":["Confirm the target MCP server is running and registered in Nacos under the exact serviceName in serviceRef (check Nacos console service list).","Verify namespace, group and cluster names in McpServiceRef match those the MCP server registered with.","Check instance health status in Nacos; restart or re-register unhealthy instances.","Wrap the tool call with retry/fallback logic since endpoint availability can be transient."],"exampleFix":"// before\nMcpServiceRef ref = McpServiceRef.builder().serviceName(\"my-mcp\").build(); // wrong namespace\n// after\nMcpServiceRef ref = McpServiceRef.builder().serviceName(\"my-mcp\").namespace(\"public\").groupName(\"DEFAULT_GROUP\").build();","handlingStrategy":"retry","validationCode":"McpEndpointInfo ep = nacosMcpOperationService.selectEndpoint(serviceRef);\nif (ep == null) { throw new IllegalStateException(\"Precheck: MCP service not resolvable: \" + serviceRef.getServiceName()); }","typeGuard":null,"tryCatchPattern":"try { return callback.call(args); }\ncatch (RuntimeException e) {\n    if (e.getMessage() != null && e.getMessage().startsWith(\"No available endpoint found\")) {\n        return retry.withBackoff(3, call); // endpoint discovery is transient\n    }\n    throw e;\n}","preventionTips":["Monitor the MCP service's healthy instance count in Nacos","Keep namespace/group names consistent between gateway and MCP servers","Add health checks so deregistered servers are caught before tool calls"],"tags":["nacos","service-discovery","no-endpoint","mcp"],"backgroundTag":"empty-result-set","analyzedSha":"f82da0b50f35744c13968191be2b1cd2452ef550","analyzedAt":"2026-09-09T15:32:42.421Z","contentChangedAt":"2026-09-09T15:32:42.421Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}