{"record":{"id":"7179322127f00fd0","repo":"openzipkin/zipkin","slug":"cannot-read-keyspace-metadata-for-keyspace-s-and","errorCode":null,"errorMessage":"Cannot read keyspace metadata for keyspace: %s and cluster: %s","messagePattern":"Cannot read keyspace metadata for keyspace: (.+?) and cluster: (.+?)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"critical","filePath":"zipkin-storage/cassandra/src/main/java/zipkin2/storage/cassandra/Schema.java","lineNumber":126,"sourceCode":"    LOG.debug(\"Registering endpoint and annotation UDTs to keyspace {}\", keyspace);\n    TypeCodec<UdtValue> endpointUDTCodec =\n      codecRegistry.codecFor(ks.getUserDefinedType(\"endpoint\").get());\n    codecRegistry.register(new EndpointCodec(endpointUDTCodec));\n  }\n\n  static final class Metadata {\n    final boolean hasAutocompleteTags, hasRemoteService;\n\n    Metadata(boolean hasAutocompleteTags, boolean hasRemoteService) {\n      this.hasAutocompleteTags = hasAutocompleteTags;\n      this.hasRemoteService = hasRemoteService;\n    }\n  }\n\n  static KeyspaceMetadata ensureKeyspaceMetadata(CqlSession session, String keyspace) {\n    KeyspaceMetadata keyspaceMetadata = session.getMetadata().getKeyspace(keyspace).orElse(null);\n    if (keyspaceMetadata == null) {\n      throw new IllegalStateException(\n        \n          \"Cannot read keyspace metadata for keyspace: %s and cluster: %s\".formatted(\n          keyspace, session.getMetadata().getClusterName()));\n    }\n    return keyspaceMetadata;\n  }\n\n  static Version ensureVersion(com.datastax.oss.driver.api.core.metadata.Metadata metadata) {\n    Version version = null;\n    for (Map.Entry<UUID, Node> entry : metadata.getNodes().entrySet()) {\n      version = entry.getValue().getCassandraVersion();\n      if (version == null) throw new RuntimeException(\"node had no version: \" + entry.getValue());\n      if (Version.parse(\"3.11.3\").compareTo(version) > 0) {\n        throw new RuntimeException(\n          \"Node %s is running Cassandra %s, but minimum version is 3.11.3\".formatted(\n          entry.getKey(), entry.getValue().getCassandraVersion()));\n      }\n    }","sourceCodeStart":108,"sourceCodeEnd":144,"githubUrl":"https://github.com/openzipkin/zipkin/blob/878ce2a1fad54ca941d17fdcf2e1d924b148eb1f/zipkin-storage/cassandra/src/main/java/zipkin2/storage/cassandra/Schema.java#L108-L144","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check the keyspace name in the error against what exists in Cassandra (DESCRIBE KEYSPACES).","Create the keyspace or let ensureSchema=true install the full schema before UDT usage.","Verify the connected user can see the keyspace in system_schema."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"if (session.getMetadata().getKeyspace(keyspace).isEmpty()) {\n  throw new IllegalStateException(\"Keyspace '\" + keyspace + \"' not visible; check CASSANDRA_KEYSPACE and user grants\");\n}","typeGuard":null,"tryCatchPattern":"catch (IllegalStateException e) { if (e.getMessage().contains(\"Cannot read keyspace metadata\")) fixOrCreateKeyspace(); else throw e; }","preventionTips":["Spell-check CASSANDRA_KEYSPACE against DESCRIBE KEYSPACES output.","For remote-keyspace setups (DSE/Astra), attach the keyspace before starting Zipkin."],"tags":["cassandra","zipkin","keyspace","metadata","configuration"],"backgroundTag":null,"analyzedSha":"878ce2a1fad54ca941d17fdcf2e1d924b148eb1f","analyzedAt":"2026-08-14T15:17:09.895Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}