prestodb/presto · error · PrestoException

CASSANDRA_METADATA_ERROR

CASSANDRA_METADATA_ERROR

Error message

The cluster metadata is not available. Please make sure that the Cassandra cluster is up and running, and that the contact points are specified correctly.

What it means

getSplits needs the cluster's token ranges to build token-based splits; if the driver session returns an empty token range set, the connector cannot plan scans and throws CASSANDRA_METADATA_ERROR. This typically means the driver failed to fetch cluster metadata (schema/token metadata disabled or cluster unreachable).

Source

Thrown at presto-cassandra/src/main/java/com/facebook/presto/cassandra/CassandraTokenSplitManager.java:65

    @Inject
    public CassandraTokenSplitManager(CassandraSession session, CassandraClientConfig config)
    {
        this(session, config.getSplitSize(), config.getSplitsPerNode());
    }

    public CassandraTokenSplitManager(CassandraSession session, int splitSize, Optional<Long> configSplitsPerNode)
    {
        this.session = requireNonNull(session, "session is null");
        this.splitSize = splitSize;
        this.configSplitsPerNode = configSplitsPerNode;
    }

    public List<TokenSplit> getSplits(String keyspace, String table, Optional<Long> sessionSplitsPerNode)
    {
        Set<TokenRange> tokenRanges = session.getTokenRanges();

        if (tokenRanges.isEmpty()) {
            throw new PrestoException(CASSANDRA_METADATA_ERROR, "The cluster metadata is not available. " +
                    "Please make sure that the Cassandra cluster is up and running, " +
                    "and that the contact points are specified correctly.");
        }

        if (tokenRanges.stream().anyMatch(TokenRange::isWrappedAround)) {
            tokenRanges = unwrap(tokenRanges);
        }

        Optional<TokenRing> tokenRing = createForPartitioner(session.getPartitioner());
        long totalPartitionsCount = getTotalPartitionsCount(keyspace, table, sessionSplitsPerNode);

        List<TokenSplit> splits = new ArrayList<>();
        for (TokenRange tokenRange : tokenRanges) {
            if (tokenRange.isEmpty()) {
                continue;
            }
            checkState(!tokenRange.isWrappedAround(), "all token ranges must be unwrapped at this step");

View on GitHub (pinned to 55bb57d202)

Solutions

Verify Cassandra is running and contact points in the catalog properties are correct (cassandra.contact-points)
Test connectivity to the contact point ports (9042) from the Presto coordinator/worker nodes
Ensure driver metadata is enabled so token ranges are populated (do not disable schema/token metadata)
Restart the Presto coordinator or reopen the Cassandra session to force metadata refresh

Example fix

// before: etc/catalog/cassandra.properties
cassandra.contact-points=deadhost

// after
cassandra.contact-points=cassandra1,cassandra2,cassandra3

Defensive patterns

Strategy: validation

Validate before calling

CassandraSession s = cassandraCluster.getAnySession();
if (s.getClusterMetadata() == null
        || Iterables.isEmpty(s.getClusterMetadata().getTokenRanges())) {
    throw new IllegalStateException("No token ranges available; check Cassandra contact points");
}

Try / catch

try {
    List<TokenSplit> splits = splitManager.getSplits(keyspace, table, splitsPerNode);
} catch (PrestoException e) {
    if (CASSANDRA_METADATA_ERROR.toErrorCode().getCode() == e.getErrorCode().getCode()) {
        waitForClusterOrAlert(); // nodetool status / health check before retry
    }
    throw e;
}

Prevention

Verify cassandra.contact-points point at live nodes before starting queries
Monitor Cassandra control-connection health from Presto nodes
Do not disable driver token/schema metadata
Run readiness checks so queries only start when Cassandra is up

When it happens

Trigger: Running any query that requires splits (SELECT) when session.getTokenRanges() returns empty — Cassandra unreachable at planning time, driver metadata/ token-map disabled, or the driver session lost metadata after startup.

Common situations: Contact points misconfigured or pointing at a dead node; cassandra.load-policy / metadata options that disable token metadata; network/firewall blocking the driver's control connection; Cassandra still bootstrapping when queries arrive.

Related errors

AI-assisted analysis of prestodb/presto@55bb57d202 (2026-09-04). Data as JSON: /api/errors/1b419a60fe366f8f. Report an issue: GitHub.