apache/cassandra · critical · InitializationException

Failed to connect to JMX

Error message

Failed to connect to JMX

What it means

When opening the JMX connection fails with IOException or SecurityException, the invoker prints the root cause (e.g. connection refused, auth failure) and wraps it in InitializationException 'Failed to connect to JMX'. It signals the target node's JMX endpoint is unreachable or denied.

Source

Thrown at src/java/org/apache/cassandra/tools/nodetool/JmxConnect.java:134

        {
            if (isNotEmpty(username))
            {
                if (isNotEmpty(passwordFilePath))
                    password = readUserPasswordFromFile(username, passwordFilePath);

                if (isEmpty(password))
                    password = promptAndReadPassword();
            }

            probe(username.isEmpty() ? nodeProbeFactory.create(host, parseInt(port))
                                     : nodeProbeFactory.create(host, parseInt(port), username, password));
        }
        catch (IOException | SecurityException e)
        {
            Throwable rootCause = Throwables.getRootCause(e);
            output.printError("nodetool: Failed to connect to '%s:%s' - %s: '%s'.%n", host, port,
                         rootCause.getClass().getSimpleName(), rootCause.getMessage());
            throw new InitializationException("Failed to connect to JMX", e);
        }
    }

    @Override
    public void close() throws Exception
    {
        if (probe() == null)
            return;
        ((AutoCloseable) probe()).close();
    }

    private static String readUserPasswordFromFile(String username, String passwordFilePath)
    {
        String password = EMPTY;

        File passwordFile = new File(passwordFilePath);
        try (Scanner scanner = new Scanner(passwordFile.toJavaIOFile()).useDelimiter("\\s+"))
        {

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Verify the node is up and JMX is listening: netstat/ss on the JMX port (default 7199)
2. Set correct host/port on the nodetool -h/-p flags and check cassandra-env.sh JMX settings
3. If authentication is enabled, supply credentials or fix conf/cassandra-env.sh LOCAL_JMX/remote JMX setup
4. Check TLS/SSL settings match between client and server

Example fix

// before
nodetool -h 10.0.0.99 -p 7199 jmx status
// after
nodetool -h 127.0.0.1 -p 7199 jmx status   # or start JMX on the node

// check reachability before invoking
new Socket().connect(new InetSocketAddress(host, jmxPort), 3000); // throws if unreachable

try { invoker.execute(parseResult); } catch (InitializationException e) { if (e.getMessage().contains("Failed to connect")) { /* check host/port/creds, retry */ } }

When it happens

Trigger: Node down; wrong host/port (JMX_PORT, cassandra-env JMX_REMOTE_PORT); firewall blocking; JMX authentication (cassandra-env LOCAL_JMX=yes vs remote) rejecting the credentials; SSL mismatch.

Common situations: Nodetool run off-host without remote JMX enabled; password file keystore misconfiguration; TLS cert hostname mismatch; java security policy blocks access.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

• failed to connect to %s for streaming data
• Could not retrieve list of stat mbeans.
• Error occured when getting the guardrails config
• Failed to close JMX connection
• Connection Error

AI-assisted analysis of apache/cassandra@88fd0f6a0e (2026-09-10). Data as JSON: /api/errors/820ff9e53c9562f6. Report an issue: GitHub.