{"record":{"id":"0f9e3f957873aa3e","repo":"openzipkin/zipkin","slug":"node-s-is-running-cassandra-s-but-minimum-versi","errorCode":null,"errorMessage":"Node %s is running Cassandra %s, but minimum version is 3.11.3","messagePattern":"Node (.+?) is running Cassandra (.+?), but minimum version is 3\\.11\\.3","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"zipkin-storage/cassandra/src/main/java/zipkin2/storage/cassandra/Schema.java","lineNumber":140,"sourceCode":"\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    }\n    if (version == null) throw new RuntimeException(\"No nodes in the cluster\");\n    LOG.info(\"Detected Cassandra version {}\", version);\n    return version;\n  }\n\n  static void ensureExists(CqlSession session, String keyspace, boolean searchEnabled) {\n    KeyspaceMetadata result = session.getMetadata().getKeyspace(keyspace).orElse(null);\n    Version version = ensureVersion(session.getMetadata());\n    if (result == null || result.getTable(Schema.TABLE_SPAN).isEmpty()) {\n      LOG.info(\"Installing schema {} for keyspace {}\", SCHEMA_RESOURCE, keyspace);\n      applyCqlFile(version, keyspace, session, SCHEMA_RESOURCE);\n      if (searchEnabled) {\n        LOG.info(\"Installing indexes {} for keyspace {}\", INDEX_RESOURCE, keyspace);\n        applyCqlFile(version, keyspace, session, INDEX_RESOURCE);","sourceCodeStart":122,"sourceCodeEnd":158,"githubUrl":"https://github.com/openzipkin/zipkin/blob/878ce2a1fad54ca941d17fdcf2e1d924b148eb1f/zipkin-storage/cassandra/src/main/java/zipkin2/storage/cassandra/Schema.java#L122-L158","documentation":"ensureVersion throws when any node in the cluster runs a Cassandra older than 3.11.3, the minimum Zipkin supports. The message names the offending node UUID and its version. Older servers lack features/behavior the schema and queries rely on, so Zipkin refuses to proceed rather than corrupt data.","triggerScenarios":"Schema ensure/validate against a mixed or legacy cluster where at least one node reports < 3.11.3 (e.g. 3.11.2, 2.x).","commonSituations":"Long-lived clusters never upgraded; rolling upgrades where one replica node is still old; local dev with an ancient Cassandra container image.","solutions":["Upgrade every node in the cluster to Cassandra 3.11.3 or newer (ideally a recent 3.11.x or 4.x).","Verify no stale/decommissioned nodes linger in cluster metadata; force a driver metadata refresh or restart the client.","Pin dev/test environments to a supported image (e.g. cassandra:3.11.16 or 4.x)."],"exampleFix":"# before\ndocker run cassandra:3.0\n\n# after\ndocker run cassandra:4.1","handlingStrategy":"validation","validationCode":"for (Node n : session.getMetadata().getNodes().values()) {\n  if (n.getCassandraVersion() != null && Version.parse(\"3.11.3\").compareTo(n.getCassandraVersion()) > 0)\n    throw new IllegalStateException(\"Node below minimum Cassandra 3.11.3: \" + n);\n}","typeGuard":null,"tryCatchPattern":"catch (RuntimeException e) { if (e.getMessage() != null && e.getMessage().contains(\"minimum version\")) failDeploymentWithUpgradeTask(); else throw e; }","preventionTips":["Pin CI and dev Cassandra images to >= 3.11.3.","Complete rolling upgrades (all nodes) before pointing Zipkin at the cluster."],"tags":["cassandra","zipkin","version","upgrade","compatibility"],"backgroundTag":null,"analyzedSha":"878ce2a1fad54ca941d17fdcf2e1d924b148eb1f","analyzedAt":"2026-08-14T15:17:09.895Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}