{"record":{"id":"cfaecb310f537773","repo":"openzipkin/zipkin","slug":"schema-lacks-indexing-apply-s-or-set-cassandra","errorCode":null,"errorMessage":"schema lacks indexing: apply %s, or set CASSANDRA_ENSURE_SCHEMA=true","messagePattern":"schema lacks indexing: apply (.+?), or set CASSANDRA_ENSURE_SCHEMA=true","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"zipkin-storage/cassandra/src/main/java/zipkin2/storage/cassandra/Schema.java","lineNumber":96,"sourceCode":"        \"schema lacks autocomplete indexing: apply {}, or set CASSANDRA_ENSURE_SCHEMA=true\",\n        UPGRADE_1);\n    }\n\n    if (!hasRemoteService) {\n      LOG.warn(\n        \"schema lacks remote service indexing: apply {}, or set CASSANDRA_ENSURE_SCHEMA=true\",\n        UPGRADE_2);\n    }\n\n    return md;\n  }\n\n  static void logAndThrow(String messageFormat, Object... args) {\n    String message = messageFormat.formatted(args);\n    // Ensure we can look at logs to see the problem. Otherwise, it may only\n    // be visible in API error responses, such as /health or /api/v2/traces.\n    LOG.error(message);\n    throw new RuntimeException(message);\n  }\n\n  static void initializeUDTs(CqlSession session, String keyspace) {\n    KeyspaceMetadata ks = session.getMetadata().getKeyspace(keyspace).get();\n    MutableCodecRegistry codecRegistry =\n      (MutableCodecRegistry) session.getContext().getCodecRegistry();\n\n    TypeCodec<UdtValue> annotationUDTCodec =\n      codecRegistry.codecFor(ks.getUserDefinedType(\"annotation\").get());\n    codecRegistry.register(new AnnotationCodec(annotationUDTCodec));\n\n    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 {","sourceCodeStart":78,"sourceCodeEnd":114,"githubUrl":"https://github.com/openzipkin/zipkin/blob/878ce2a1fad54ca941d17fdcf2e1d924b148eb1f/zipkin-storage/cassandra/src/main/java/zipkin2/storage/cassandra/Schema.java#L78-L114","documentation":"Schema validation throws a RuntimeException with 'schema lacks indexing: apply %s, or set CASSANDRA_ENSURE_SCHEMA=true' when the keyspace exists but is missing the search/index tables (e.g. span_annotations with indexing) that Zipkin requires for query support. Like the other schema errors it is logged at ERROR then rethrown.","triggerScenarios":"An old Zipkin schema version was installed before index tables existed, and ensureSchema=false so validation catches the gap; search indexes were only conditionally installed (searchEnabled) but queries are enabled.","commonSituations":"Upgrading Zipkin against a long-lived Cassandra keyspace; a cluster where someone applied only the base schema cql and not the index cql.","solutions":["Set CASSANDRA_ENSURE_SCHEMA=true to let Zipkin apply the missing index/schema upgrade, then optionally turn it back off.","Or manually apply the referenced upgrade/index cql file named in the error message.","Re-run schema validation (e.g. hit /health) after applying to confirm the keyspace passes."],"exampleFix":"// before\nCASSANDRA_ENSURE_SCHEMA=false\n\n// after (one-time, then revert)\nCASSANDRA_ENSURE_SCHEMA=true","handlingStrategy":"validation","validationCode":"// Verify index/search tables exist before locking ensureSchema=false\nKeyspaceMetadata ks = session.getMetadata().getKeyspace(keyspace).orElseThrow();\nboolean hasIndexes = ks.getTable(\"span_annotations\").isPresent() && ks.getTable(\"remote_service_names\").isPresent();\nif (!hasIndexes) throw new IllegalStateException(\"Apply index schema/upgrade first\");","typeGuard":null,"tryCatchPattern":"catch (RuntimeException e) { if (e.getMessage() != null && e.getMessage().contains(\"schema lacks\")) { runOneTimeEnsureSchema(); } else throw e; }","preventionTips":["After every Zipkin upgrade, run one boot with CASSANDRA_ENSURE_SCHEMA=true, verify /health, then disable it.","Track applied schema versions per environment like a migration changelog."],"tags":["cassandra","zipkin","schema","upgrade","indexing"],"backgroundTag":null,"analyzedSha":"878ce2a1fad54ca941d17fdcf2e1d924b148eb1f","analyzedAt":"2026-08-14T15:17:09.895Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}