openzipkin/zipkin · critical · IllegalStateException

Cannot read keyspace metadata for keyspace: %s and cluster:

Error message

Cannot read keyspace metadata for keyspace: %s and cluster: %s

What it means

ensureKeyspaceMetadata throws IllegalStateException('Cannot read keyspace metadata for keyspace: %s and cluster: %s') when session.getMetadata().getKeyspace(keyspace) returns empty. The driver knows the cluster but not this keyspace, meaning the keyspace does not exist (or is not visible to the connected user) at the time metadata was read.

Source

Thrown at zipkin-storage/cassandra/src/main/java/zipkin2/storage/cassandra/Schema.java:126

    LOG.debug("Registering endpoint and annotation UDTs to keyspace {}", keyspace);
    TypeCodec<UdtValue> endpointUDTCodec =
      codecRegistry.codecFor(ks.getUserDefinedType("endpoint").get());
    codecRegistry.register(new EndpointCodec(endpointUDTCodec));
  }

  static final class Metadata {
    final boolean hasAutocompleteTags, hasRemoteService;

    Metadata(boolean hasAutocompleteTags, boolean hasRemoteService) {
      this.hasAutocompleteTags = hasAutocompleteTags;
      this.hasRemoteService = hasRemoteService;
    }
  }

  static KeyspaceMetadata ensureKeyspaceMetadata(CqlSession session, String keyspace) {
    KeyspaceMetadata keyspaceMetadata = session.getMetadata().getKeyspace(keyspace).orElse(null);
    if (keyspaceMetadata == null) {
      throw new IllegalStateException(
        
          "Cannot read keyspace metadata for keyspace: %s and cluster: %s".formatted(
          keyspace, session.getMetadata().getClusterName()));
    }
    return keyspaceMetadata;
  }

  static Version ensureVersion(com.datastax.oss.driver.api.core.metadata.Metadata metadata) {
    Version version = null;
    for (Map.Entry<UUID, Node> entry : metadata.getNodes().entrySet()) {
      version = entry.getValue().getCassandraVersion();
      if (version == null) throw new RuntimeException("node had no version: " + entry.getValue());
      if (Version.parse("3.11.3").compareTo(version) > 0) {
        throw new RuntimeException(
          "Node %s is running Cassandra %s, but minimum version is 3.11.3".formatted(
          entry.getKey(), entry.getValue().getCassandraVersion()));
      }
    }

View on GitHub (pinned to 878ce2a1fa)

Solutions

1. Check the keyspace name in the error against what exists in Cassandra (DESCRIBE KEYSPACES).
2. Create the keyspace or let ensureSchema=true install the full schema before UDT usage.
3. Verify the connected user can see the keyspace in system_schema.

if (session.getMetadata().getKeyspace(keyspace).isEmpty()) {
  throw new IllegalStateException("Keyspace '" + keyspace + "' not visible; check CASSANDRA_KEYSPACE and user grants");
}

catch (IllegalStateException e) { if (e.getMessage().contains("Cannot read keyspace metadata")) fixOrCreateKeyspace(); else throw e; }

When it happens

Trigger: Calling schema ensure/validate with a keyspace name that was never created (typo in CASSANDRA_KEYSPACE), or when Schema.initializeUDTs runs before the keyspace exists. Note ensureExists creates the keyspace, so this usually fires from the UDT-registration path in LazySession.

Common situations: CASSANDRA_KEYSPACE typo (e.g. zipkin vs zipkin3); a DSE/Astra remote-keyspace setup where the keyspace is not attached; permissions that hide the keyspace from metadata.

Related errors

• keyspace == null
• autocompleteTtl <= 0
• autocompleteCardinality <= 0
• contactPoints == null
• maxConnections <= 0

AI-assisted analysis of openzipkin/zipkin@878ce2a1fa (2026-08-14). Data as JSON: /api/errors/7179322127f00fd0. Report an issue: GitHub.