zitadel/zitadel · critical

initialize database failed: %w

Error message

initialize database failed: %w

What it means

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.

Source

Thrown at cmd/initialise/init.go:81

				err = errors.Join(err, shutdown(cmd.Context()))
			}()

			return InitAll(cmd.Context(), config)
		},
	}

	cmd.AddCommand(newSchema(), newDatabase(), newUser(), newGrant())
	return cmd
}

func InitAll(ctx context.Context, config *Config) error {
	err := initialise(ctx, config.Database,
		VerifyUser(config.Database.Username(), config.Database.Password()),
		VerifyDatabase(config.Database.DatabaseName()),
		VerifyGrant(config.Database.DatabaseName(), config.Database.Username()),
	)
	if err != nil {
		return fmt.Errorf("initialize database failed: %w", err)
	}

	err = verifyZitadel(ctx, config.Database)
	if err != nil {
		return fmt.Errorf("initialize ZITADEL failed: %w", err)
	}
	return nil
}

func initialise(ctx context.Context, config database.Config, steps ...func(context.Context, *database.DB) error) error {
	logging.Info(ctx, "initialization started")

	err := ReadStmts()
	if err != nil {
		return err
	}

	db, err := database.Connect(config, true)

View on GitHub (pinned to 13948f2bcd)

Solutions

1. Check the wrapped error's root cause: connection refused → verify host/port/credentials in config.database.postgres.admin
2. Ensure the admin user has CREATEDB and CREATEROLE privileges (or is a superuser) so users, database and grants can be created
3. If running in Docker/k8s, add retry/wait-for-postgres logic; the DB may not be accepting connections yet
4. Run the init command manually (zitadel init --config ...) to see the full error outside the container entrypoint

Example fix

// before (config.yaml)
database:
  postgres:
    admin:
      username: postgres
      password: wrong
// after
database:
  postgres:
    admin:
      username: postgres
      password: <correct-superuser-password>

func canInitDatabase(ctx context.Context, adminDSN string) error {
	db, err := sql.Open("pgx", adminDSN)
	if err != nil {
		return err
	}
	defer db.Close()
	var one int
	if err := db.QueryRowContext(ctx, "SELECT 1").Scan(&one); err != nil {
		return fmt.Errorf("admin connection failed: %w", err)
	}
	var canCreate bool
	if err := db.QueryRowContext(ctx,
		"SELECT rolcreatedb AND rolcreaterole FROM pg_roles WHERE rolname = current_user",
	).Scan(&canCreate); err != nil || !canCreate {
		return fmt.Errorf("admin role lacks CREATEDB/CREATEROLE (err=%v)", err)
	}
	return nil
}

err := initialise.InitAll(ctx, config)
if err != nil {
	var pgErr *pgconn.PgError
	if errors.As(err, &pgErr) {
		log.Fatalf("init failed with pg error %s (code %s): %s", pgErr.Message, pgErr.Code, pgErr.Detail)
	}
	log.Fatalf("initialize database failed: %v", err)
}

When it happens

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

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

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

• initialize ZITADEL failed: %w
• MaxOpenConns of the database must be higher than 3 or 0 for
• MaxIdleConns of the database must be higher than 3 or 0 for
• unable to get current database: %w
• unable to check if database exists: %w

AI-assisted analysis of zitadel/zitadel@13948f2bcd (2026-09-06). Data as JSON: /api/errors/7e348c23b1d0aef8. Report an issue: GitHub.