{"record":{"id":"22e7ae2b093d5715","repo":"temporalio/temporal","slug":"sql-schema-version-compatibility-check-failed-w","errorCode":null,"errorMessage":"sql schema version compatibility check failed: %w","messagePattern":"sql schema version compatibility check failed: %w","errorType":"console","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"temporal/fx.go","lineNumber":959,"sourceCode":"func 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//\n// - []go.opentelemetry.io/otel/sdk/trace.SpanExporter\nvar TraceExportModule = fx.Options(\n\tfx.Provide(func(inputs SpanExporterInputs) ([]otelsdktrace.SpanExporter, error) {\n\t\t// (1) Exporters from config.","sourceCodeStart":941,"sourceCodeEnd":977,"githubUrl":"https://github.com/temporalio/temporal/blob/bde624efd13fbd3843654058db6d9c716166318b/temporal/fx.go#L941-L977","documentation":"Wraps the error from sql.VerifyCompatibleVersion during startup schema validation for SQL stores (Postgres, MySQL, SQLite). Temporal requires the database schema version to be compatible with this binary.","triggerScenarios":"Server bootstrap; a SQL datastore in the persistence config has a schema_version table with an incompatible version, a missing schema, or the version query itself fails.","commonSituations":"Deploying a newer Temporal server without running temporal-sql-tool update-schema; fresh database with no schema applied; wrong database name in config pointing at an empty/unrelated DB.","solutions":["Run temporal-sql-tool update-schema to apply the required schema version","Use validate-schema to check version compatibility before starting","Confirm the configured database name matches the one with the Temporal schema applied","Check DB connectivity if the version check itself errored"],"exampleFix":"// before\n# start server on fresh DB\ntemporal-server start\n// after\ntemporal-sql-tool --ep localhost -p 5432 -u temporal --pw secret --db temporal update-schema\ntemporal-server start","handlingStrategy":"validation","validationCode":"// before starting the server\ncmd := exec.Command(\"temporal-sql-tool\",\n    \"--ep\", host, \"-u\", user, \"--pw\", pass, \"--db\", dbName,\n    \"validate-schema\", \"--schema-version\", requiredVersion)\nif err := cmd.Run(); err != nil {\n    return fmt.Errorf(\"run temporal-sql-tool update-schema first\")\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Run temporal-sql-tool update-schema as part of every server upgrade","Verify the configured DB name hosts the Temporal schema","Add schema version checks to deployment pipelines"],"tags":["sql","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"}