{"record":{"id":"8a3fc89c7a18899e","repo":"alibaba/arthas","slug":"arthas-failed-to-bind-telnet-or-http-port-telnet","errorCode":null,"errorMessage":"Arthas failed to bind telnet or http port! Telnet port: ${configure.getTelnetPort()}, http port: ${configure.getHttpPort()}","messagePattern":"Arthas failed to bind telnet or http port! Telnet port: (.+?), http port: (.+?)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"critical","filePath":"core/src/main/java/com/taobao/arthas/core/server/ArthasBootstrap.java","lineNumber":476,"sourceCode":"                logger().info(\"try to bind http server, host: {}, port: {}.\", configure.getIp(), configure.getHttpPort());\n                shellServer.registerTermServer(new HttpTermServer(configure.getIp(), configure.getHttpPort(),\n                        options.getConnectionTimeout(), workerGroup, httpSessionManager));\n            } else {\n                // listen local address in VM communication\n                if (configure.getTunnelServer() != null) {\n                    shellServer.registerTermServer(new HttpTermServer(configure.getIp(), configure.getHttpPort(),\n                            options.getConnectionTimeout(), workerGroup, httpSessionManager));\n                }\n                logger().info(\"http port is {}, skip bind http server.\", configure.getHttpPort());\n            }\n\n            for (CommandResolver resolver : resolvers) {\n                shellServer.registerCommandResolver(resolver);\n            }\n\n            shellServer.listen(new BindHandler(isBindRef));\n            if (!isBind()) {\n                throw new IllegalStateException(\"Arthas failed to bind telnet or http port! Telnet port: \"\n                        + String.valueOf(configure.getTelnetPort()) + \", http port: \"\n                        + String.valueOf(configure.getHttpPort()));\n            }\n\n            //http api session manager\n            sessionManager = new SessionManagerImpl(options, shellServer.getCommandManager(), shellServer.getJobController());\n            //http api handler\n            httpApiHandler = new HttpApiHandler(historyManager, sessionManager);\n\n            // Mcp Server\n            String mcpEndpoint = configure.getMcpEndpoint();\n            String mcpProtocol = configure.getMcpProtocol();\n            if (mcpEndpoint != null && !mcpEndpoint.trim().isEmpty()) {\n                logger().info(\"try to start mcp server, endpoint: {}, protocol: {}.\", mcpEndpoint, mcpProtocol);\n                CommandExecutor commandExecutor = new CommandExecutorImpl(sessionManager);\n                this.arthasMcpBootstrap = new ArthasMcpBootstrap(commandExecutor, mcpEndpoint, mcpProtocol);\n                this.mcpRequestHandler = this.arthasMcpBootstrap.start().getMcpRequestHandler();\n            }","sourceCodeStart":458,"sourceCodeEnd":494,"githubUrl":"https://github.com/alibaba/arthas/blob/21cf2e9ba52b305290be7223b980ff504bb9cb5b/core/src/main/java/com/taobao/arthas/core/server/ArthasBootstrap.java#L458-L494","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before: default ports conflict\n$ java -jar arthas-boot.jar\n// -> Arthas failed to bind telnet or http port! Telnet port: 3658, http port: 8563\n\n// after: specify free ports\n$ java -jar arthas-boot.jar --telnet-port 3659 --http-port 8564","handlingStrategy":"validation","validationCode":"// Check ports are free before starting Arthas\nimport java.net.ServerSocket;\nvoid checkFree(int... ports) throws IOException {\n    for (int p : ports) {\n        if (p <= 0) continue;\n        try (ServerSocket s = new ServerSocket(p)) { }\n        catch (IOException e) { throw new IOException(\"Port \" + p + \" in use\", e); }\n    }\n}\ncheckFree(3658, 8563);","typeGuard":null,"tryCatchPattern":"try {\n    arthasBootstrap.start();\n} catch (IllegalStateException e) {\n    if (e.getMessage().contains(\"failed to bind\")) {\n        // pick new ports and retry, or report to user\n        log.error(\"Port conflict, try --telnet-port/--http-port with free values\");\n    }\n    throw e;\n}","preventionTips":["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."],"tags":["network","port-binding","startup","telnet","http"],"backgroundTag":null,"analyzedSha":"21cf2e9ba52b305290be7223b980ff504bb9cb5b","analyzedAt":"2026-08-14T00:57:07.243Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}