temporalio/temporal · critical

sql schema version compatibility check failed: %w

Error message

sql schema version compatibility check failed: %w

What it means

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.

Source

Thrown at temporal/fx.go:959

func ServerLifetimeHooks(
	lc fx.Lifecycle,
	svr *ServerImpl,
) {
	lc.Append(fx.StartStopHook(svr.Start, svr.Stop))
}

func verifyPersistenceCompatibleVersion(
	cfg config.Persistence,
	persistenceServiceResolver resolver.ServiceResolver,
	logger log.Logger,
) error {
	// cassandra schema version validation
	if err := cassandra.VerifyCompatibleVersion(cfg, persistenceServiceResolver, logger); err != nil {
		return fmt.Errorf("cassandra schema version compatibility check failed: %w", err)
	}
	// sql schema version validation
	if err := sql.VerifyCompatibleVersion(cfg, persistenceServiceResolver, logger); err != nil {
		return fmt.Errorf("sql schema version compatibility check failed: %w", err)
	}
	return nil
}

type SpanExporterInputs struct {
	fx.In
	Lifecycyle fx.Lifecycle
	Config     *config.Config `optional:"true"`
}

// TraceExportModule holds process-global telemetry fx state defining the set of
// OTEL trace/span exporters used by tracing instrumentation. The following
// types can be overriden/augmented with fx.Replace/fx.Decorate:
//
// - []go.opentelemetry.io/otel/sdk/trace.SpanExporter
var TraceExportModule = fx.Options(
	fx.Provide(func(inputs SpanExporterInputs) ([]otelsdktrace.SpanExporter, error) {
		// (1) Exporters from config.

View on GitHub (pinned to bde624efd1)

Solutions

1. Run temporal-sql-tool update-schema to apply the required schema version
2. Use validate-schema to check version compatibility before starting
3. Confirm the configured database name matches the one with the Temporal schema applied
4. Check DB connectivity if the version check itself errored

Example fix

// before
# start server on fresh DB
temporal-server start
// after
temporal-sql-tool --ep localhost -p 5432 -u temporal --pw secret --db temporal update-schema
temporal-server start

// before starting the server
cmd := exec.Command("temporal-sql-tool",
    "--ep", host, "-u", user, "--pw", pass, "--db", dbName,
    "validate-schema", "--schema-version", requiredVersion)
if err := cmd.Run(); err != nil {
    return fmt.Errorf("run temporal-sql-tool update-schema first")
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• cassandra schema version compatibility check failed: %w
• %w: unknown plugin %q, supported plugins: %v
• %v rows were affected instead of 1
• unable to create Elasticsearch client (URL = %v, username =
• error initializing cluster metadata manager: %w

AI-assisted analysis of temporalio/temporal@bde624efd1 (2026-09-01). Data as JSON: /api/errors/22e7ae2b093d5715. Report an issue: GitHub.