alibaba/arthas · critical · RuntimeException

Failed to start Arthas MCP server

Error message

Failed to start Arthas MCP server

What it means

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.

Source

Thrown at core/src/main/java/com/taobao/arthas/core/mcp/ArthasMcpServer.java:140

            unifiedMcpHandler = McpHttpRequestHandler.builder()
                    .mcpEndpoint(properties.getMcpEndpoint())
                    .objectMapper(properties.getObjectMapper())
                    .protocol(properties.getProtocol())
                    .build();

            if (properties.getProtocol() == ServerProtocol.STREAMABLE) {
                startStreamableServer(properties, toolClassification);
            } else {
                startStatelessServer(properties, toolClassification);
            }

            logger.info("Arthas MCP server started successfully");
            logger.info("- MCP Endpoint: {}", properties.getMcpEndpoint());
            logger.info("- Transport mode: {}", properties.getProtocol());
        } catch (Exception e) {
            logger.error("Failed to start Arthas MCP server", e);
            throw new RuntimeException("Failed to start Arthas MCP server", e);
        }
    }

    /**
     * 扫描并分类工具
     */
    private ToolClassification scanAndClassifyTools() {
        DefaultToolCallbackProvider toolCallbackProvider = new DefaultToolCallbackProvider();
        toolCallbackProvider.setToolBasePackage(ARTHAS_TOOL_BASE_PACKAGE);
        
        ToolCallback[] allCallbacks = toolCallbackProvider.getToolCallbacks();
        
        // 根据 taskSupport 属性分类工具
        List<ToolCallback> requiredTaskTools = new ArrayList<>();  // taskSupport=required
        List<ToolCallback> optionalTaskTools = new ArrayList<>();  // taskSupport=optional
        List<ToolCallback> normalTools = new ArrayList<>();        // taskSupport=forbidden
        
        for (ToolCallback callback : allCallbacks) {

View on GitHub (pinned to 21cf2e9ba5)

Solutions

1. Read the logged cause (logger.error prints it) to identify the exact failing step.
2. If the cause is a bind error, free the endpoint/port or change the configured endpoint.
3. Verify the ARTHAS_TOOL_BASE_PACKAGE tools are present and annotated correctly so scanAndClassifyTools succeeds.
4. Ensure the protocol value matches a supported ServerProtocol enum (STREAMABLE / stateless).

Example fix

// before
mcpServer.start();  // port 8080 in use
// after
// configure mcpEndpoint to a free port, then
mcpServer.start();

// Verify the endpoint is bindable and tools are discoverable before start()
try (ServerSocket s = new ServerSocket(port)) { /* port free */ }
if (toolCallbacks == null || toolCallbacks.length == 0)
    log.warn("No MCP tools found under base package");

null

try {
    mcpServer.start();
} catch (RuntimeException e) {
    Throwable root = e.getCause() != null ? e.getCause() : e;
    log.error("MCP start failed: {}", root.getMessage(), root);
    if (root instanceof java.net.BindException) {
        // free/change the endpoint, then retry
    }
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Failed to initialize Arthas MCP server
• Arthas server port binding failed! Please check $HOME/logs/a
• Arthas server port binding failed! Please check $HOME/logs/a
• 必须提供 path 或 cursor
• offset 不允许为负数

AI-assisted analysis of alibaba/arthas@21cf2e9ba5 (2026-08-14). Data as JSON: /api/errors/04178a0b5dd997d9. Report an issue: GitHub.