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

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.

Source

Thrown at agent/src/main/java/com/taobao/arthas/agent334/AgentBootstrap.java:188

                // ignore
            }
            throw new RuntimeException(t);
        }
    }

    private static void bind(Instrumentation inst, ClassLoader agentLoader, String args) throws Throwable {
        /**
         * <pre>
         * ArthasBootstrap bootstrap = ArthasBootstrap.getInstance(inst);
         * </pre>
         */
        Class<?> bootstrapClass = agentLoader.loadClass(ARTHAS_BOOTSTRAP);
        Object bootstrap = bootstrapClass.getMethod(GET_INSTANCE, Instrumentation.class, String.class).invoke(null, inst, args);
        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.";
            ps.println(errorMsg);
            throw new RuntimeException(errorMsg);
        }
        ps.println("Arthas server already bind.");
    }

    private static String decodeArg(String arg) {
        try {
            return URLDecoder.decode(arg, "utf-8");
        } catch (UnsupportedEncodingException e) {
            return arg;
        }
    }
}

View on GitHub (pinned to 21cf2e9ba5)

Solutions

1. Read $HOME/logs/arthas/arthas.log for the underlying bind exception.
2. Free the conflicting port or start arthas with explicit ports (e.g., --telnet-port / --http-port) that are free.
3. Stop any prior arthas session on the target JVM before re-attaching.

Example fix

// before
java -jar arthas-boot.jar <pid>
// -> Arthas server port binding failed!

// after
java -jar arthas-boot.jar <pid> --telnet-port 3659 --http-port 8564

boolean portFree(int p) {
  try (java.net.Socket s = new java.net.Socket("127.0.0.1", p)) { return false; }
  catch (java.io.IOException e) { return true; }
}
if (!portFree(3658) || !portFree(8563)) { System.err.println("arthas ports busy"); }

try { bootstrap.bind(...); }
catch (RuntimeException e) { if (e.getMessage().contains("port binding failed")) { useAlternatePorts(); } else throw e; }

When it happens

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

Common situations: Attaching arthas twice to the same JVM; another tool occupies the ports; SELinux/firewall blocks the bind; insufficient privileges.

Related errors

• Arthas server port binding failed! Please check $HOME/logs/a
• Failed to initialize Arthas MCP server
• Failed to start Arthas MCP server
• Arthas failed to bind telnet or http port! Telnet port: ${co
• ERROR: arthas vmtool Unable to create jvmtiEnv, GetEnv faile

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