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.

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();
Defensive patterns

Strategy: try-catch

Validate before calling

// 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");

Type guard

null

Try / catch

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
    }
}

Prevention

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

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

Appendix: 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)