{"record":{"id":"7e348c23b1d0aef8","repo":"zitadel/zitadel","slug":"initialize-database-failed-w","errorCode":null,"errorMessage":"initialize database failed: %w","messagePattern":"initialize database failed: %w","errorType":"console","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"cmd/initialise/init.go","lineNumber":81,"sourceCode":"\t\t\t\terr = errors.Join(err, shutdown(cmd.Context()))\n\t\t\t}()\n\n\t\t\treturn InitAll(cmd.Context(), config)\n\t\t},\n\t}\n\n\tcmd.AddCommand(newSchema(), newDatabase(), newUser(), newGrant())\n\treturn cmd\n}\n\nfunc InitAll(ctx context.Context, config *Config) error {\n\terr := initialise(ctx, config.Database,\n\t\tVerifyUser(config.Database.Username(), config.Database.Password()),\n\t\tVerifyDatabase(config.Database.DatabaseName()),\n\t\tVerifyGrant(config.Database.DatabaseName(), config.Database.Username()),\n\t)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"initialize database failed: %w\", err)\n\t}\n\n\terr = verifyZitadel(ctx, config.Database)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"initialize ZITADEL failed: %w\", err)\n\t}\n\treturn nil\n}\n\nfunc initialise(ctx context.Context, config database.Config, steps ...func(context.Context, *database.DB) error) error {\n\tlogging.Info(ctx, \"initialization started\")\n\n\terr := ReadStmts()\n\tif err != nil {\n\t\treturn err\n\t}\n\n\tdb, err := database.Connect(config, true)","sourceCodeStart":63,"sourceCodeEnd":99,"githubUrl":"https://github.com/zitadel/zitadel/blob/13948f2bcd6f257794dbd6d342c2ac30bc88fe54/cmd/initialise/init.go#L63-L99","documentation":"InitAll runs the initialise() sequence (user, database, grant verification steps) against the configured database and wraps any failure as \"initialize database failed\". It means one of the setup steps — creating the ZITADEL service user, database, or grants — failed to execute. The wrapped error carries the failing step and the SQL-level cause.","triggerScenarios":"initialise(ctx, config.Database, VerifyUser(...), VerifyDatabase(...), VerifyGrant(...)) returns an error: any step fails, most commonly because the admin DB connection could not be established or a SQL statement (CREATE USER/DATABASE/GRANT) failed.","commonSituations":"Docker entrypoint init with wrong postgres admin credentials or host; admin user lacking CREATEDB/CREATEROLE privileges; database server not yet ready during container startup; network/firewall blocking port 5432.","solutions":["Check the wrapped error's root cause: connection refused → verify host/port/credentials in config.database.postgres.admin","Ensure the admin user has CREATEDB and CREATEROLE privileges (or is a superuser) so users, database and grants can be created","If running in Docker/k8s, add retry/wait-for-postgres logic; the DB may not be accepting connections yet","Run the init command manually (zitadel init --config ...) to see the full error outside the container entrypoint"],"exampleFix":"// before (config.yaml)\ndatabase:\n  postgres:\n    admin:\n      username: postgres\n      password: wrong\n// after\ndatabase:\n  postgres:\n    admin:\n      username: postgres\n      password: <correct-superuser-password>","handlingStrategy":"validation","validationCode":"func canInitDatabase(ctx context.Context, adminDSN string) error {\n\tdb, err := sql.Open(\"pgx\", adminDSN)\n\tif err != nil {\n\t\treturn err\n\t}\n\tdefer db.Close()\n\tvar one int\n\tif err := db.QueryRowContext(ctx, \"SELECT 1\").Scan(&one); err != nil {\n\t\treturn fmt.Errorf(\"admin connection failed: %w\", err)\n\t}\n\tvar canCreate bool\n\tif err := db.QueryRowContext(ctx,\n\t\t\"SELECT rolcreatedb AND rolcreaterole FROM pg_roles WHERE rolname = current_user\",\n\t).Scan(&canCreate); err != nil || !canCreate {\n\t\treturn fmt.Errorf(\"admin role lacks CREATEDB/CREATEROLE (err=%v)\", err)\n\t}\n\treturn nil\n}","typeGuard":null,"tryCatchPattern":"err := initialise.InitAll(ctx, config)\nif err != nil {\n\tvar pgErr *pgconn.PgError\n\tif errors.As(err, &pgErr) {\n\t\tlog.Fatalf(\"init failed with pg error %s (code %s): %s\", pgErr.Message, pgErr.Code, pgErr.Detail)\n\t}\n\tlog.Fatalf(\"initialize database failed: %v\", err)\n}","preventionTips":["Ensure the admin DB user has CREATEDB and CREATEROLE before first init","Add a wait-for-database step before running init in containers","Test the admin DSN with psql before deploying","Keep init and setup steps in order: init → setup → start"],"tags":["database","postgres","initialization"],"backgroundTag":"database-query-failed","analyzedSha":"13948f2bcd6f257794dbd6d342c2ac30bc88fe54","analyzedAt":"2026-09-06T10:16:19.814Z","contentChangedAt":"2026-09-06T10:16:19.814Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}