temporalio/temporal · critical

cassandra schema version compatibility check failed: %w

Error message

cassandra schema version compatibility check failed: %w

What it means

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.

Source

Thrown at temporal/fx.go:955

func PersistenceFactoryProvider() persistenceClient.FactoryProviderFn {
	return persistenceClient.FactoryProvider
}

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:
//

View on GitHub (pinned to bde624efd1)

Solutions

1. Run temporal-cassandra-tool -k <keyspace> update-schema to bring schema to the required version
2. Run validate-schema to check current vs required version
3. Verify the Cassandra keyspace in persistence config is the schema-managed one
4. Ensure Cassandra is reachable (connection failure also surfaces here)

Example fix

// before: starting new binary directly
temporal-server start
// after: upgrade schema first
temporal-cassandra-tool -k temporal update-schema
temporal-server start

// before starting the server
cmd := exec.Command("temporal-cassandra-tool", "-k", keyspace,
    "validate-schema", "--schema-version", requiredVersion)
if err := cmd.Run(); err != nil {
    return fmt.Errorf("run update-schema before starting the server")
}

When it happens

Trigger: Server bootstrap calls verifyPersistenceVersionCompatibility; the configured persistence includes Cassandra and its schema version is missing, too old, or too new for this Temporal build.

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

Related errors

• sql schema version compatibility check failed: %w
• invalid task schema version
• %w. provided table version: %v current table version: %v
• 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/d7cc622d8981f397. Report an issue: GitHub.