alibaba/arthas · critical · RuntimeException

Arthas server port binding failed! Please check $HOME/logs/a

Error message

Arthas server port binding failed! Please check $HOME/logs/arthas/arthas.log for more details.

What it means

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.

Source

Thrown at arthas-agent-attach/src/main/java/com/taobao/arthas/agent/attach/ArthasAgent.java:126

            File arthasCoreJarFile = new File(arthasHome, ARTHAS_CORE_JAR);
            if (!arthasCoreJarFile.exists()) {
                throw new IllegalStateException("can not find arthas-core.jar under arthasHome: " + arthasHome);
            }
            AttachArthasClassloader arthasClassLoader = new AttachArthasClassloader(
                    new URL[] { arthasCoreJarFile.toURI().toURL() });

            /**
             * <pre>
             * ArthasBootstrap bootstrap = ArthasBootstrap.getInstance(inst);
             * </pre>
             */
            Class<?> bootstrapClass = arthasClassLoader.loadClass(ARTHAS_BOOTSTRAP);
            Object bootstrap = bootstrapClass.getMethod(GET_INSTANCE, Instrumentation.class, Map.class).invoke(null,
                    instrumentation, configMap);
            boolean isBind = (Boolean) bootstrapClass.getMethod(IS_BIND).invoke(bootstrap);
            if (!isBind) {
                String errorMsg = "Arthas server port binding failed! Please check $HOME/logs/arthas/arthas.log for more details.";
                throw new RuntimeException(errorMsg);
            }
        } catch (Throwable e) {
            errorMessage = e.getMessage();
            if (!slientInit) {
                throw new IllegalStateException(e);
            }
        }
    }

    private static File createTempDir() {
        File baseDir = new File(System.getProperty("java.io.tmpdir"));
        String baseName = "arthas-" + System.currentTimeMillis() + "-";

        for (int counter = 0; counter < TEMP_DIR_ATTEMPTS; counter++) {
            File tempDir = new File(baseDir, baseName + counter);
            if (tempDir.mkdir()) {
                return tempDir;
            }

View on GitHub (pinned to 21cf2e9ba5)

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.

Example fix

// before
agent.attach(config); // default ports in use

// after
config.put("arthasHome", home);
config.put("telnetPort", "3659");
config.put("httpPort", "8564");
agent.attach(config);

Defensive patterns

Strategy: try-catch

Validate before calling

boolean portsFree = portFree(3658) && portFree(8563);
if (!portsFree) { config.put("telnetPort", "3659"); config.put("httpPort", "8564"); }

Try / catch

try { agent.attach(config); }
catch (IllegalStateException e) { if (e.getCause() != null && e.getCause().getMessage().contains("port binding failed")) { reattachWithFreePorts(config); } else throw e; }

Prevention

Detach existing arthas sessions first.
Pass explicit free ports in the config map.
Inspect arthas.log on failure.

When it happens

Trigger: 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.

Common situations: Repeated attaches without stopping prior sessions; port conflict; environment restrictions on opening the listen socket.

Related errors

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