{"record":{"id":"e05f566935d318e5","repo":"alibaba/arthas","slug":"arthas-server-port-binding-failed-please-check-h","errorCode":null,"errorMessage":"Arthas server port binding failed! Please check $HOME/logs/arthas/arthas.log for more details.","messagePattern":"Arthas server port binding failed! Please check \\$HOME/logs/arthas/arthas\\.log for more details\\.","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"agent/src/main/java/com/taobao/arthas/agent334/AgentBootstrap.java","lineNumber":188,"sourceCode":"                // ignore\n            }\n            throw new RuntimeException(t);\n        }\n    }\n\n    private static void bind(Instrumentation inst, ClassLoader agentLoader, String args) throws Throwable {\n        /**\n         * <pre>\n         * ArthasBootstrap bootstrap = ArthasBootstrap.getInstance(inst);\n         * </pre>\n         */\n        Class<?> bootstrapClass = agentLoader.loadClass(ARTHAS_BOOTSTRAP);\n        Object bootstrap = bootstrapClass.getMethod(GET_INSTANCE, Instrumentation.class, String.class).invoke(null, inst, args);\n        boolean isBind = (Boolean) bootstrapClass.getMethod(IS_BIND).invoke(bootstrap);\n        if (!isBind) {\n            String errorMsg = \"Arthas server port binding failed! Please check $HOME/logs/arthas/arthas.log for more details.\";\n            ps.println(errorMsg);\n            throw new RuntimeException(errorMsg);\n        }\n        ps.println(\"Arthas server already bind.\");\n    }\n\n    private static String decodeArg(String arg) {\n        try {\n            return URLDecoder.decode(arg, \"utf-8\");\n        } catch (UnsupportedEncodingException e) {\n            return arg;\n        }\n    }\n}\n","sourceCodeStart":170,"sourceCodeEnd":201,"githubUrl":"https://github.com/alibaba/arthas/blob/21cf2e9ba52b305290be7223b980ff504bb9cb5b/agent/src/main/java/com/taobao/arthas/agent334/AgentBootstrap.java#L170-L201","documentation":"Thrown by AgentBootstrap.bind() after ArthasBootstrap.getInstance() returns a bootstrap whose isBind() is false, meaning Arthas failed to bring up its telnet/http server. The real cause (port in use, bind exception, init error) is in $HOME/logs/arthas/arthas.log; this message only signals the outcome.","triggerScenarios":"Default arthas ports (telnet 3658, http 8563) are already in use by another arthas session or process; the bootstrap started but the netty/telnet server threw during bind; a previous attach left a session bound to the same JVM.","commonSituations":"Attaching arthas twice to the same JVM; another tool occupies the ports; SELinux/firewall blocks the bind; insufficient privileges.","solutions":["Read $HOME/logs/arthas/arthas.log for the underlying bind exception.","Free the conflicting port or start arthas with explicit ports (e.g., --telnet-port / --http-port) that are free.","Stop any prior arthas session on the target JVM before re-attaching."],"exampleFix":"// before\njava -jar arthas-boot.jar <pid>\n// -> Arthas server port binding failed!\n\n// after\njava -jar arthas-boot.jar <pid> --telnet-port 3659 --http-port 8564","handlingStrategy":"validation","validationCode":"boolean portFree(int p) {\n  try (java.net.Socket s = new java.net.Socket(\"127.0.0.1\", p)) { return false; }\n  catch (java.io.IOException e) { return true; }\n}\nif (!portFree(3658) || !portFree(8563)) { System.err.println(\"arthas ports busy\"); }","typeGuard":null,"tryCatchPattern":"try { bootstrap.bind(...); }\ncatch (RuntimeException e) { if (e.getMessage().contains(\"port binding failed\")) { useAlternatePorts(); } else throw e; }","preventionTips":["Check ports 3658/8563 before launching arthas.","Always tail $HOME/logs/arthas/arthas.log on bind failure.","Detach prior sessions before re-attaching."],"tags":["arthas","agent","port-binding","startup"],"backgroundTag":null,"analyzedSha":"21cf2e9ba52b305290be7223b980ff504bb9cb5b","analyzedAt":"2026-08-14T00:57:07.243Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}