{"record":{"id":"77ca0bcb1812e886","repo":"temporalio/temporal","slug":"unable-to-initialize-metadata-manager-w","errorCode":null,"errorMessage":"unable to initialize metadata manager: %w","messagePattern":"unable to initialize metadata manager: %w","errorType":"console","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"temporal/server_impl.go","lineNumber":185,"sourceCode":"\t\tmetricsHandler,\n\t\ttelemetry.NoopTracerProvider,\n\t\tserializer,\n\t)\n\tfactory := persistenceFactoryProvider(persistenceClient.NewFactoryParams{\n\t\tDataStoreFactory:           dataStoreFactory,\n\t\tCfg:                        cfg,\n\t\tPersistenceMaxQPS:          nil,\n\t\tPersistenceNamespaceMaxQPS: nil,\n\t\tClusterName:                persistenceClient.ClusterName(currentClusterName),\n\t\tMetricsHandler:             metricsHandler,\n\t\tLogger:                     logger,\n\t\tSerializer:                 serializer,\n\t})\n\tdefer factory.Close()\n\n\tmetadataManager, err := factory.NewMetadataManager()\n\tif err != nil {\n\t\treturn fmt.Errorf(\"unable to initialize metadata manager: %w\", err)\n\t}\n\tdefer metadataManager.Close()\n\tctx, cancel := context.WithTimeout(\n\t\theaders.SetCallerInfo(ctx, headers.SystemBackgroundHighCallerInfo),\n\t\t30*time.Second,\n\t)\n\tdefer cancel()\n\n\tif err = metadataManager.InitializeSystemNamespaces(ctx, currentClusterName); err != nil {\n\t\treturn fmt.Errorf(\"unable to register system namespace: %w\", err)\n\t}\n\treturn nil\n}\n","sourceCodeStart":167,"sourceCodeEnd":199,"githubUrl":"https://github.com/temporalio/temporal/blob/bde624efd13fbd3843654058db6d9c716166318b/temporal/server_impl.go#L167-L199","documentation":"Wraps the error from factory.NewMetadataManager() while bootstrapping system namespaces. The metadata manager is the persistence component that reads/writes namespaces; constructing it validates the underlying data store (SQL/Cassandra) and schema. If the datastore is unreachable, credentials are wrong, or the metadata tables/schema version are missing or incompatible, this error is returned and server startup aborts.","triggerScenarios":"temporal.Server.Start(ctx) -> initSystemNamespaces, when the persistence factory cannot construct a MetadataManager: DB connection failure (bad host/port/user/password), missing metadata tables (schema not applied), unsupported or outdated schema version, or bad persistence config for the selected plugin.","commonSituations":"Fresh deployment where temporal-sql-tool setup was skipped; wrong plugin selected in config (e.g. cassandra vs mysql); network policy/segfault-free firewall blocking the DB port; password rotation in env not reflected in config; running a newer Temporal binary against an older schema that needs update-schema.","solutions":["Read the wrapped cause for the concrete DB error (connection refused, access denied, table not found)","Apply/upgrade the persistence schema: temporal-sql-tool setup + update-schema for your plugin and version","Verify persistence config in your config yaml: plugin, host, port, credentials, database name, and that the DB is reachable (try connecting with a DB client)","Confirm the plugin matches the deployed datastore (mysql/postgres/cassandra/sqlite) and required extensions/versions","Check schema_version_compatibility in config against the actual schema version in the database"],"exampleFix":"// before: config.yaml points to database 'temporal' but only 'default' schema was created\n// unable to initialize metadata manager: Table 'temporal.namespaces' doesn't exist\n\n// after: create schema and tables first\n// temporal-sql-tool --plugin mysql --ep $DB --db temporal setup\n// temporal-sql-tool --plugin mysql --ep $DB --db temporal update-schema -d schema/mysql/v57/temporal/versioned","handlingStrategy":"validation","validationCode":"// before starting the server, verify DB connectivity and schema:\n// db, err := sql.Open(\"mysql\", dsn)\n// if err != nil { return err }\n// if err := db.Ping(); err != nil { return fmt.Errorf(\"datastore unreachable: %w\", err) }\n// var exists int\n// db.QueryRow(\"SELECT COUNT(*) FROM information_schema.tables WHERE table_schema='temporal' AND table_name='namespaces'\").Scan(&exists)\n// if exists == 0 { return errors.New(\"schema not applied: run temporal-sql-tool setup + update-schema\") }","typeGuard":null,"tryCatchPattern":"if err := srv.Start(ctx); err != nil {\n\tif strings.Contains(err.Error(), \"unable to initialize metadata manager\") {\n\t\tlog.Fatalf(\"check persistence config and schema: %v\", errors.Unwrap(err))\n\t}\n\tlog.Fatal(err)\n}","preventionTips":["Run temporal-sql-tool setup and update-schema as part of every deployment","Keep DB credentials in secrets/env synced with persistence config","Match the persistence plugin in config to the actual datastore","Check schema version compatibility config after Temporal upgrades","Test DB reachability from the server network/namespace (firewalls, service meshes)"],"tags":["persistence","metadata","database","startup"],"backgroundTag":"database-connection-failed","analyzedSha":"bde624efd13fbd3843654058db6d9c716166318b","analyzedAt":"2026-09-01T07:18:39.080Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}