What causes "Failed to initialize Arthas MCP server" in alibaba/arthas?

Inspect the logged cause (logger.error logs the full exception) — fix the root failure it reports (often error 92).

alibaba/arthas · critical · RuntimeException

Failed to initialize Arthas MCP server

Error message

Failed to initialize Arthas MCP server

What it means

Thrown as a RuntimeException by ArthasMcpBootstrap.start() wrapping any Exception that occurs while creating or starting the MCP server (the inner ArthasMcpServer construction or its start() call). The bootstrap logs the underlying cause and rethrows, so the original exception is available as the cause for diagnostics.

Source

Thrown at core/src/main/java/com/taobao/arthas/core/mcp/ArthasMcpBootstrap.java:52

    }

    public ArthasMcpServer start() {
        logger.info("Initializing Arthas MCP Bootstrap...");
        try {
            logger.debug("Creating MCP server instance with command executor: {}", 
                    commandExecutor.getClass().getSimpleName());
            
            // Create and start MCP server with CommandExecutor and custom endpoint
            mcpServer = new ArthasMcpServer(mcpEndpoint, commandExecutor, protocol);
            logger.debug("MCP server instance created successfully");
            
            mcpServer.start();
            logger.info("Arthas MCP server initialized successfully");
            logger.info("Bootstrap ready - server is operational");
            return mcpServer;
        } catch (Exception e) {
            logger.error("Failed to initialize Arthas MCP server", e);
            throw new RuntimeException("Failed to initialize Arthas MCP server", e);
        }
    }

    public void shutdown() {
        logger.info("Initiating Arthas MCP Bootstrap shutdown...");
        if (mcpServer != null) {
            logger.debug("Stopping MCP server...");
            mcpServer.stop();
            logger.info("MCP server stopped");
        } else {
            logger.warn("MCP server was null during shutdown - may not have been properly initialized");
        }
        logger.info("Arthas MCP Bootstrap shutdown completed");
    }
}

View on GitHub (pinned to 21cf2e9ba5)

Solutions

Inspect the logged cause (logger.error logs the full exception) — fix the root failure it reports (often error 92).
Ensure the mcpEndpoint is free and correctly formatted, and the protocol is 'streamable' or 'stateless'.
Confirm the CommandExecutor passed to the bootstrap is non-null and initialised.
Retry after freeing the port / fixing configuration.

Example fix

// before
new ArthasMcpBootstrap(executor, endpoint, protocol).start();  // endpoint busy
// after
// free the port / use a free endpoint, then start
new ArthasMcpBootstrap(executor, freeEndpoint, protocol).start();

Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-checks before starting the bootstrap
Objects.requireNonNull(commandExecutor, "commandExecutor");
if (mcpEndpoint == null || mcpEndpoint.trim().isEmpty())
    throw new IllegalArgumentException("mcpEndpoint required");

Type guard

null

Try / catch

try {
    bootstrap.start();
} catch (RuntimeException e) {
    // 'Failed to initialize Arthas MCP server' — inspect e.getCause()
    Throwable root = e.getCause() != null ? e.getCause() : e;
    log.error("MCP init failed; root cause: {}", root.getMessage(), root);
    // fix the root cause (often error 92: port/endpoint in use), then retry
}

Prevention

Inspect the wrapped cause to find the real failure (usually error 92).
Ensure the MCP endpoint is free and the protocol is valid before start().
Pass a non-null, initialised CommandExecutor.

When it happens

Trigger: Calling ArthasMcpBootstrap.start() when the MCP endpoint is invalid/unavailable, the CommandExecutor is misconfigured, port binding fails, or the inner server start throws. Any exception inside the try block (lines 38-49) triggers this.

Common situations: MCP endpoint already in use; null CommandExecutor; protocol misconfiguration; tool scanning failure propagating up; the inner 'Failed to start Arthas MCP server' (error 92) bubbling through here.

Related errors

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