{"record":{"id":"62a1012230cfef9d","repo":"zitadel/zitadel","slug":"cannot-start-db-client-for-queries-w","errorCode":null,"errorMessage":"cannot start DB client for queries: %w","messagePattern":"cannot start DB client for queries: %w","errorType":"console","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"cmd/start/start.go","lineNumber":184,"sourceCode":"\tKeys       *encryption.EncryptionKeys\n\tEventstore *eventstore.Eventstore\n\tQueries    *query.Queries\n\tAuthzRepo  authz_repo.Repository\n\tStorage    static.Storage\n\tCommands   *command.Commands\n\tRouter     *mux.Router\n\tTLSConfig  *tls.Config\n\tShutdown   chan<- os.Signal\n}\n\nfunc startZitadel(ctx context.Context, config *Config, masterKey string, server chan<- *Server) error {\n\tshowBasicInformation(config)\n\n\ti18n.MustLoadSupportedLanguagesFromDir()\n\n\tdbClient, err := database.Connect(config.Database, false)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"cannot start DB client for queries: %w\", err)\n\t}\n\tnew_domain.SetPool(v3_postgres.PGxPool(dbClient.Pool))\n\n\tkeyStorage, err := cryptoDB.NewKeyStorage(dbClient, masterKey)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"cannot start key storage: %w\", err)\n\t}\n\tkeys, err := encryption.EnsureEncryptionKeys(ctx, config.EncryptionKeys, keyStorage)\n\tif err != nil {\n\t\treturn err\n\t}\n\tq, err := queue.NewQueue(&queue.Config{\n\t\tClient: dbClient,\n\t})\n\tif err != nil {\n\t\treturn err\n\t}\n","sourceCodeStart":166,"sourceCodeEnd":202,"githubUrl":"https://github.com/zitadel/zitadel/blob/13948f2bcd6f257794dbd6d342c2ac30bc88fe54/cmd/start/start.go#L166-L202","documentation":"startZitadel calls database.Connect to create the primary PGx pool for queries. If the connection to the configured PostgreSQL database cannot be established, the error is wrapped as 'cannot start DB client for queries'. ZITADEL cannot serve any traffic without this client, so startup aborts.","triggerScenarios":"database.Connect(config.Database, false) fails: wrong host/port/user/password/database in config, TLS misconfiguration, DNS failure, or the Postgres server is unreachable.","commonSituations":"Postgres not yet ready in docker-compose/K8s (startup race), wrong ZITADEL_DATABASE_POSTGRES_* env vars, firewall/network policy blocking 5432, bad SSL mode or expired certificates.","solutions":["Verify the wrapped error and test connectivity with psql using the exact connection parameters from your config","Confirm Postgres is running and reachable (docker compose ps / kubectl get pods) and wait for readiness","Check host, port, user, password, database, ssl_mode in config or ZITADEL_DATABASE_POSTGRES_* environment variables","If Postgres starts slower than ZITADEL, add readiness gating/retries (e.g. depends_on: condition: service_healthy)"],"exampleFix":"// before\ndatabase:\n  postgres:\n    host: db\n    port: 5433\n// after\ndatabase:\n  postgres:\n    host: db\n    port: 5432","handlingStrategy":"retry","validationCode":"// before starting, probe the DB\nnc, err := net.DialTimeout(\"tcp\", net.JoinHostPort(host, port), 3*time.Second)\nif err != nil { return fmt.Errorf(\"postgres unreachable: %w\", err) }\nnc.Close()","typeGuard":null,"tryCatchPattern":"if err := waitForPostgres(cfg, 30*time.Second); err != nil {\n    log.Fatalf(\"DB not reachable in time: %v\", err)\n}","preventionTips":["Use healthcheck-gated orchestration (depends_on: service_healthy)","Keep a single source of truth for DB credentials (env/secret manager)","Test connectivity with psql from inside the container before startup"],"tags":["database","postgres","startup","connection"],"backgroundTag":"connection-refused","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"}