{"record":{"id":"c71b0702efb1fdd8","repo":"alibaba/arthas","slug":"arthas-server-port-binding-failed-please-check-h-c71b07","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":"arthas-agent-attach/src/main/java/com/taobao/arthas/agent/attach/ArthasAgent.java","lineNumber":126,"sourceCode":"            File arthasCoreJarFile = new File(arthasHome, ARTHAS_CORE_JAR);\n            if (!arthasCoreJarFile.exists()) {\n                throw new IllegalStateException(\"can not find arthas-core.jar under arthasHome: \" + arthasHome);\n            }\n            AttachArthasClassloader arthasClassLoader = new AttachArthasClassloader(\n                    new URL[] { arthasCoreJarFile.toURI().toURL() });\n\n            /**\n             * <pre>\n             * ArthasBootstrap bootstrap = ArthasBootstrap.getInstance(inst);\n             * </pre>\n             */\n            Class<?> bootstrapClass = arthasClassLoader.loadClass(ARTHAS_BOOTSTRAP);\n            Object bootstrap = bootstrapClass.getMethod(GET_INSTANCE, Instrumentation.class, Map.class).invoke(null,\n                    instrumentation, configMap);\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                throw new RuntimeException(errorMsg);\n            }\n        } catch (Throwable e) {\n            errorMessage = e.getMessage();\n            if (!slientInit) {\n                throw new IllegalStateException(e);\n            }\n        }\n    }\n\n    private static File createTempDir() {\n        File baseDir = new File(System.getProperty(\"java.io.tmpdir\"));\n        String baseName = \"arthas-\" + System.currentTimeMillis() + \"-\";\n\n        for (int counter = 0; counter < TEMP_DIR_ATTEMPTS; counter++) {\n            File tempDir = new File(baseDir, baseName + counter);\n            if (tempDir.mkdir()) {\n                return tempDir;\n            }","sourceCodeStart":108,"sourceCodeEnd":144,"githubUrl":"https://github.com/alibaba/arthas/blob/21cf2e9ba52b305290be7223b980ff504bb9cb5b/arthas-agent-attach/src/main/java/com/taobao/arthas/agent/attach/ArthasAgent.java#L108-L144","documentation":"Same bind-failure condition as error 12 but on the arthas-agent-attach path: after reflectively invoking ArthasBootstrap.getInstance(...), isBind() returns false, so the netty/telnet/http server did not start. When slientInit is false the failure is rethrown as IllegalStateException; when true it is swallowed into errorMessage.","triggerScenarios":"Default ports occupied by a prior arthas session; bootstrap initialization error during attach; attaching to a JVM where a prior arthas session is half-bound.","commonSituations":"Repeated attaches without stopping prior sessions; port conflict; environment restrictions on opening the listen socket.","solutions":["Detach any existing arthas session on the target JVM first.","Provide free telnet/http ports in the attach config map.","Inspect $HOME/logs/arthas/arthas.log for the concrete bind failure."],"exampleFix":"// before\nagent.attach(config); // default ports in use\n\n// after\nconfig.put(\"arthasHome\", home);\nconfig.put(\"telnetPort\", \"3659\");\nconfig.put(\"httpPort\", \"8564\");\nagent.attach(config);","handlingStrategy":"try-catch","validationCode":"boolean portsFree = portFree(3658) && portFree(8563);\nif (!portsFree) { config.put(\"telnetPort\", \"3659\"); config.put(\"httpPort\", \"8564\"); }","typeGuard":null,"tryCatchPattern":"try { agent.attach(config); }\ncatch (IllegalStateException e) { if (e.getCause() != null && e.getCause().getMessage().contains(\"port binding failed\")) { reattachWithFreePorts(config); } else throw e; }","preventionTips":["Detach existing arthas sessions first.","Pass explicit free ports in the config map.","Inspect arthas.log on failure."],"tags":["arthas","agent-attach","port-binding","startup"],"backgroundTag":null,"analyzedSha":"21cf2e9ba52b305290be7223b980ff504bb9cb5b","analyzedAt":"2026-08-14T00:57:07.243Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}