{"record":{"id":"1b419a60fe366f8f","repo":"prestodb/presto","slug":"cassandra-metadata-error","errorCode":"CASSANDRA_METADATA_ERROR","errorMessage":"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.","messagePattern":"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\\.","errorType":"error_code","errorClass":"PrestoException","httpStatus":null,"severity":"error","filePath":"presto-cassandra/src/main/java/com/facebook/presto/cassandra/CassandraTokenSplitManager.java","lineNumber":65,"sourceCode":"    @Inject\n    public CassandraTokenSplitManager(CassandraSession session, CassandraClientConfig config)\n    {\n        this(session, config.getSplitSize(), config.getSplitsPerNode());\n    }\n\n    public CassandraTokenSplitManager(CassandraSession session, int splitSize, Optional<Long> configSplitsPerNode)\n    {\n        this.session = requireNonNull(session, \"session is null\");\n        this.splitSize = splitSize;\n        this.configSplitsPerNode = configSplitsPerNode;\n    }\n\n    public List<TokenSplit> getSplits(String keyspace, String table, Optional<Long> sessionSplitsPerNode)\n    {\n        Set<TokenRange> tokenRanges = session.getTokenRanges();\n\n        if (tokenRanges.isEmpty()) {\n            throw new PrestoException(CASSANDRA_METADATA_ERROR, \"The cluster metadata is not available. \" +\n                    \"Please make sure that the Cassandra cluster is up and running, \" +\n                    \"and that the contact points are specified correctly.\");\n        }\n\n        if (tokenRanges.stream().anyMatch(TokenRange::isWrappedAround)) {\n            tokenRanges = unwrap(tokenRanges);\n        }\n\n        Optional<TokenRing> tokenRing = createForPartitioner(session.getPartitioner());\n        long totalPartitionsCount = getTotalPartitionsCount(keyspace, table, sessionSplitsPerNode);\n\n        List<TokenSplit> splits = new ArrayList<>();\n        for (TokenRange tokenRange : tokenRanges) {\n            if (tokenRange.isEmpty()) {\n                continue;\n            }\n            checkState(!tokenRange.isWrappedAround(), \"all token ranges must be unwrapped at this step\");\n","sourceCodeStart":47,"sourceCodeEnd":83,"githubUrl":"https://github.com/prestodb/presto/blob/55bb57d202de3b926896fa966c2c4a44c779634e/presto-cassandra/src/main/java/com/facebook/presto/cassandra/CassandraTokenSplitManager.java#L47-L83","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before: etc/catalog/cassandra.properties\ncassandra.contact-points=deadhost\n\n// after\ncassandra.contact-points=cassandra1,cassandra2,cassandra3","handlingStrategy":"validation","validationCode":"CassandraSession s = cassandraCluster.getAnySession();\nif (s.getClusterMetadata() == null\n        || Iterables.isEmpty(s.getClusterMetadata().getTokenRanges())) {\n    throw new IllegalStateException(\"No token ranges available; check Cassandra contact points\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    List<TokenSplit> splits = splitManager.getSplits(keyspace, table, splitsPerNode);\n} catch (PrestoException e) {\n    if (CASSANDRA_METADATA_ERROR.toErrorCode().getCode() == e.getErrorCode().getCode()) {\n        waitForClusterOrAlert(); // nodetool status / health check before retry\n    }\n    throw e;\n}","preventionTips":["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"],"tags":["cassandra","metadata","split-planning","connectivity"],"backgroundTag":"cassandra-metadata-unavailable","analyzedSha":"55bb57d202de3b926896fa966c2c4a44c779634e","analyzedAt":"2026-09-04T12:50:26.162Z","contentChangedAt":"2026-09-04T12:50:26.162Z","schemaVersion":2},"datasetVersion":"2026-09-11T21:17:09.523Z"}