apache/cassandra · error · RuntimeException

Unable to get metadata

Error message

Unable to get metadata

What it means

maybeLoadTokenRanges reads the ring's token ranges from the driver's cluster Metadata. If cluster.getMetadata() returns null (no metadata has been fetched/constructed), a RuntimeException 'Unable to get metadata' is thrown. This typically means the client is not properly connected to the cluster.

Solutions

1. Verify the cluster is up and reachable from the stress client (nodetool status, cqlsh connect)
2. Check contact points/ports in stress settings are correct
3. Ensure the driver session established before requesting token ranges; restart stress after the cluster recovers
4. Inspect driver connection logs for metadata/control-connection failures

// ensure session is connected and metadata is loaded before stress
session.getCluster().getMetadata().getAllHosts(); // will throw if control connection failed

if (cluster.getMetadata() == null) { /* not connected - reconnect */ }

try { profile.getTokenRangeIterator(...); } catch (RuntimeException e) { if (e.getMessage().contains("Unable to get metadata")) { reconnect(); retryWithBackoff(); } else throw e; }

When it happens

Trigger: Calling getTokenRangeIterator/maybeLoadTokenRanges when the StressCQLClient's Cluster has no Metadata, e.g. driver not fully connected, connection failures at startup, or an offline/misconfigured client.

Common situations: Cluster unreachable so the driver never loaded metadata, wrong contact points, node down during stress startup, driver session closed before token ranges are read.

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

• Addresses differ: !=
• broadcast_address cannot be a wildcard address (
• Configured " " caused an exception
• Configured " " could not be found
• Configured " " was found, but had no addresses

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

Appendix: source

Thrown at tools/stress/src/org/apache/cassandra/stress/StressProfile.java:379

                tableMetaData = metadata;
            }
        }
    }

    public Set<TokenRange> maybeLoadTokenRanges(StressSettings settings)
    {
        maybeLoadSchemaInfo(settings); // ensure table metadata is available

        JavaDriverClient client = settings.getJavaDriverClient(keyspaceName);
        synchronized (client)
        {
            if (tokenRanges != null)
                return tokenRanges;

            Cluster cluster = client.getCluster();
            Metadata metadata = cluster.getMetadata();
            if (metadata == null)
                throw new RuntimeException("Unable to get metadata");

            List<TokenRange> sortedRanges = new ArrayList<>(metadata.getTokenRanges().size() + 1);
            for (TokenRange range : metadata.getTokenRanges())
            {
                //if we don't unwrap we miss the partitions between ring min and smallest range start value
                if (range.isWrappedAround())
                    sortedRanges.addAll(range.unwrap());
                else
                    sortedRanges.add(range);
            }

            Collections.sort(sortedRanges);
            tokenRanges = new LinkedHashSet<>(sortedRanges);
            return tokenRanges;
        }
    }

    public Operation getQuery(String name,

View on GitHub (pinned to 88fd0f6a0e)