alibaba/arthas · critical · IllegalStateException

Arthas failed to bind telnet or http port! Telnet port: ${co

Error message

Arthas failed to bind telnet or http port! Telnet port: ${configure.getTelnetPort()}, http port: ${configure.getHttpPort()}

What it means

Thrown after shellServer.listen() completes if isBind() still returns false, meaning neither the telnet nor the http term server successfully bound to its configured port. Arthas requires at least one reachable listener for interactive access, so it aborts startup when all bind attempts fail.

Source

Thrown at core/src/main/java/com/taobao/arthas/core/server/ArthasBootstrap.java:476

                logger().info("try to bind http server, host: {}, port: {}.", configure.getIp(), configure.getHttpPort());
                shellServer.registerTermServer(new HttpTermServer(configure.getIp(), configure.getHttpPort(),
                        options.getConnectionTimeout(), workerGroup, httpSessionManager));
            } else {
                // listen local address in VM communication
                if (configure.getTunnelServer() != null) {
                    shellServer.registerTermServer(new HttpTermServer(configure.getIp(), configure.getHttpPort(),
                            options.getConnectionTimeout(), workerGroup, httpSessionManager));
                }
                logger().info("http port is {}, skip bind http server.", configure.getHttpPort());
            }

            for (CommandResolver resolver : resolvers) {
                shellServer.registerCommandResolver(resolver);
            }

            shellServer.listen(new BindHandler(isBindRef));
            if (!isBind()) {
                throw new IllegalStateException("Arthas failed to bind telnet or http port! Telnet port: "
                        + String.valueOf(configure.getTelnetPort()) + ", http port: "
                        + String.valueOf(configure.getHttpPort()));
            }

            //http api session manager
            sessionManager = new SessionManagerImpl(options, shellServer.getCommandManager(), shellServer.getJobController());
            //http api handler
            httpApiHandler = new HttpApiHandler(historyManager, sessionManager);

            // Mcp Server
            String mcpEndpoint = configure.getMcpEndpoint();
            String mcpProtocol = configure.getMcpProtocol();
            if (mcpEndpoint != null && !mcpEndpoint.trim().isEmpty()) {
                logger().info("try to start mcp server, endpoint: {}, protocol: {}.", mcpEndpoint, mcpProtocol);
                CommandExecutor commandExecutor = new CommandExecutorImpl(sessionManager);
                this.arthasMcpBootstrap = new ArthasMcpBootstrap(commandExecutor, mcpEndpoint, mcpProtocol);
                this.mcpRequestHandler = this.arthasMcpBootstrap.start().getMcpRequestHandler();
            }

View on GitHub (pinned to 21cf2e9ba5)

Solutions

Run 'lsof -i :<telnetPort>' and 'lsof -i :<httpPort>' to find and kill the process holding the ports.
Start Arthas with explicit free ports: java -jar arthas-boot.jar --telnet-port 3659 --http-port 8564.
If you only need one transport, set the other port to -1 or 0 to skip binding it (e.g. --telnet-port -1).
Check arthas.log for the underlying bind exception (Address already in use) to confirm port conflict vs. permission error.

Example fix

// before: default ports conflict
$ java -jar arthas-boot.jar
// -> Arthas failed to bind telnet or http port! Telnet port: 3658, http port: 8563

// after: specify free ports
$ java -jar arthas-boot.jar --telnet-port 3659 --http-port 8564

Defensive patterns

Strategy: validation

Validate before calling

// Check ports are free before starting Arthas
import java.net.ServerSocket;
void checkFree(int... ports) throws IOException {
    for (int p : ports) {
        if (p <= 0) continue;
        try (ServerSocket s = new ServerSocket(p)) { }
        catch (IOException e) { throw new IOException("Port " + p + " in use", e); }
    }
}
checkFree(3658, 8563);

Try / catch

try {
    arthasBootstrap.start();
} catch (IllegalStateException e) {
    if (e.getMessage().contains("failed to bind")) {
        // pick new ports and retry, or report to user
        log.error("Port conflict, try --telnet-port/--http-port with free values");
    }
    throw e;
}

Prevention

Always specify explicit telnet-port and http-port when running multiple Arthas instances.
Kill stale Arthas/java processes before attaching.
Use telnet-port -1 if only HTTP transport is needed.

When it happens

Trigger: Both telnet and http ports are already in use by another process; or both telnetPort and httpPort are configured as null/<=0 and no tunnel server is registered; or the bind handler's callback never fires successfully due to a network error.

Common situations: A previous Arthas session did not release its ports (leftover process). Running two Arthas instances against the same JVM or two JVMs on the same host with default ports 3658/8563. Port conflicts with other services. Firewall or OS permission issues binding to the configured ip.

Related errors

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