{"record":{"id":"d7cc622d8981f397","repo":"temporalio/temporal","slug":"cassandra-schema-version-compatibility-check-faile","errorCode":null,"errorMessage":"cassandra schema version compatibility check failed: %w","messagePattern":"cassandra schema version compatibility check failed: %w","errorType":"console","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"temporal/fx.go","lineNumber":955,"sourceCode":"func PersistenceFactoryProvider() persistenceClient.FactoryProviderFn {\n\treturn persistenceClient.FactoryProvider\n}\n\nfunc ServerLifetimeHooks(\n\tlc fx.Lifecycle,\n\tsvr *ServerImpl,\n) {\n\tlc.Append(fx.StartStopHook(svr.Start, svr.Stop))\n}\n\nfunc verifyPersistenceCompatibleVersion(\n\tcfg config.Persistence,\n\tpersistenceServiceResolver resolver.ServiceResolver,\n\tlogger log.Logger,\n) error {\n\t// cassandra schema version validation\n\tif err := cassandra.VerifyCompatibleVersion(cfg, persistenceServiceResolver, logger); err != nil {\n\t\treturn fmt.Errorf(\"cassandra schema version compatibility check failed: %w\", err)\n\t}\n\t// sql schema version validation\n\tif err := sql.VerifyCompatibleVersion(cfg, persistenceServiceResolver, logger); err != nil {\n\t\treturn fmt.Errorf(\"sql schema version compatibility check failed: %w\", err)\n\t}\n\treturn nil\n}\n\ntype SpanExporterInputs struct {\n\tfx.In\n\tLifecycyle fx.Lifecycle\n\tConfig     *config.Config `optional:\"true\"`\n}\n\n// TraceExportModule holds process-global telemetry fx state defining the set of\n// OTEL trace/span exporters used by tracing instrumentation. The following\n// types can be overriden/augmented with fx.Replace/fx.Decorate:\n//","sourceCodeStart":937,"sourceCodeEnd":973,"githubUrl":"https://github.com/temporalio/temporal/blob/bde624efd13fbd3843654058db6d9c716166318b/temporal/fx.go#L937-L973","documentation":"Wraps the error from cassandra.VerifyCompatibleVersion during persistence schema validation at startup. Temporal refuses to run against a Cassandra keyspace whose schema version is incompatible with the binary.","triggerScenarios":"Server bootstrap calls verifyPersistenceVersionCompatibility; the configured persistence includes Cassandra and its schema version is missing, too old, or too new for this Temporal build.","commonSituations":"Upgrading the Temporal binary without running the schema upgrade tool; pointing at a keyspace that never had the schema applied; Cassandra cluster down so the version query fails.","solutions":["Run temporal-cassandra-tool -k <keyspace> update-schema to bring schema to the required version","Run validate-schema to check current vs required version","Verify the Cassandra keyspace in persistence config is the schema-managed one","Ensure Cassandra is reachable (connection failure also surfaces here)"],"exampleFix":"// before: starting new binary directly\ntemporal-server start\n// after: upgrade schema first\ntemporal-cassandra-tool -k temporal update-schema\ntemporal-server start","handlingStrategy":"validation","validationCode":"// before starting the server\ncmd := exec.Command(\"temporal-cassandra-tool\", \"-k\", keyspace,\n    \"validate-schema\", \"--schema-version\", requiredVersion)\nif err := cmd.Run(); err != nil {\n    return fmt.Errorf(\"run update-schema before starting the server\")\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always run update-schema after upgrading the Temporal binary","Pin schema version to the server binary version in deployment tooling","Include schema validation in CI/CD pre-deploy gates"],"tags":["cassandra","schema-version","persistence","startup","upgrade"],"backgroundTag":"schema-version-incompatible","analyzedSha":"bde624efd13fbd3843654058db6d9c716166318b","analyzedAt":"2026-09-01T07:18:39.080Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}