{"record":{"id":"04178a0b5dd997d9","repo":"alibaba/arthas","slug":"failed-to-start-arthas-mcp-server","errorCode":null,"errorMessage":"Failed to start Arthas MCP server","messagePattern":"Failed to start Arthas MCP server","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"core/src/main/java/com/taobao/arthas/core/mcp/ArthasMcpServer.java","lineNumber":140,"sourceCode":"\n            unifiedMcpHandler = McpHttpRequestHandler.builder()\n                    .mcpEndpoint(properties.getMcpEndpoint())\n                    .objectMapper(properties.getObjectMapper())\n                    .protocol(properties.getProtocol())\n                    .build();\n\n            if (properties.getProtocol() == ServerProtocol.STREAMABLE) {\n                startStreamableServer(properties, toolClassification);\n            } else {\n                startStatelessServer(properties, toolClassification);\n            }\n\n            logger.info(\"Arthas MCP server started successfully\");\n            logger.info(\"- MCP Endpoint: {}\", properties.getMcpEndpoint());\n            logger.info(\"- Transport mode: {}\", properties.getProtocol());\n        } catch (Exception e) {\n            logger.error(\"Failed to start Arthas MCP server\", e);\n            throw new RuntimeException(\"Failed to start Arthas MCP server\", e);\n        }\n    }\n\n    /**\n     * 扫描并分类工具\n     */\n    private ToolClassification scanAndClassifyTools() {\n        DefaultToolCallbackProvider toolCallbackProvider = new DefaultToolCallbackProvider();\n        toolCallbackProvider.setToolBasePackage(ARTHAS_TOOL_BASE_PACKAGE);\n        \n        ToolCallback[] allCallbacks = toolCallbackProvider.getToolCallbacks();\n        \n        // 根据 taskSupport 属性分类工具\n        List<ToolCallback> requiredTaskTools = new ArrayList<>();  // taskSupport=required\n        List<ToolCallback> optionalTaskTools = new ArrayList<>();  // taskSupport=optional\n        List<ToolCallback> normalTools = new ArrayList<>();        // taskSupport=forbidden\n        \n        for (ToolCallback callback : allCallbacks) {","sourceCodeStart":122,"sourceCodeEnd":158,"githubUrl":"https://github.com/alibaba/arthas/blob/21cf2e9ba52b305290be7223b980ff504bb9cb5b/core/src/main/java/com/taobao/arthas/core/mcp/ArthasMcpServer.java#L122-L158","documentation":"Thrown as a RuntimeException by ArthasMcpServer.start() wrapping any Exception during MCP server setup: registering JSON filters, building McpServerProperties, scanning/classifying tools, building the request handler, or starting the chosen transport (streamable vs stateless). The original exception is the cause.","triggerScenarios":"Calling ArthasMcpServer.start() when tool scanning (scanAndClassifyTools) fails, the McpHttpRequestHandler cannot be built, or the underlying transport server fails to bind to the endpoint/port. Any exception inside start()'s try block (lines 106-137) triggers this.","commonSituations":"Endpoint/port already in use; tool base package scan finds no/invalid tools; misconfigured protocol string; missing dependencies for the transport; this is usually the root cause beneath error 91.","solutions":["Read the logged cause (logger.error prints it) to identify the exact failing step.","If the cause is a bind error, free the endpoint/port or change the configured endpoint.","Verify the ARTHAS_TOOL_BASE_PACKAGE tools are present and annotated correctly so scanAndClassifyTools succeeds.","Ensure the protocol value matches a supported ServerProtocol enum (STREAMABLE / stateless)."],"exampleFix":"// before\nmcpServer.start();  // port 8080 in use\n// after\n// configure mcpEndpoint to a free port, then\nmcpServer.start();","handlingStrategy":"try-catch","validationCode":"// Verify the endpoint is bindable and tools are discoverable before start()\ntry (ServerSocket s = new ServerSocket(port)) { /* port free */ }\nif (toolCallbacks == null || toolCallbacks.length == 0)\n    log.warn(\"No MCP tools found under base package\");","typeGuard":"null","tryCatchPattern":"try {\n    mcpServer.start();\n} catch (RuntimeException e) {\n    Throwable root = e.getCause() != null ? e.getCause() : e;\n    log.error(\"MCP start failed: {}\", root.getMessage(), root);\n    if (root instanceof java.net.BindException) {\n        // free/change the endpoint, then retry\n    }\n}","preventionTips":["Read the wrapped cause to pinpoint the failing step (bind, scan, handler).","Free or change the endpoint/port before start().","Confirm the tool base package contains valid annotated tools."],"tags":["arthas","mcp","server","startup","runtime-exception"],"backgroundTag":null,"analyzedSha":"21cf2e9ba52b305290be7223b980ff504bb9cb5b","analyzedAt":"2026-08-14T00:57:07.243Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}