{"record":{"id":"575c63d06d20a5da","repo":"payloadcms/payload","slug":"error-cannot-connect-to-postgres-err-message","errorCode":null,"errorMessage":"Error: cannot connect to Postgres: ${err.message}","messagePattern":"Error: cannot connect to Postgres: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"packages/db-postgres/src/connect.ts","lineNumber":113,"sourceCode":"        `${err.message.charAt(0).toUpperCase() + err.message.slice(1)}, creating...`,\n      )\n      const isCreated = await this.createDatabase()\n\n      if (isCreated && this.connect) {\n        await this.connect(options)\n        return\n      }\n    } else {\n      this.payload.logger.error({\n        err,\n        msg: `Error: cannot connect to Postgres. Details: ${err.message}`,\n      })\n    }\n\n    if (typeof this.rejectInitializing === 'function') {\n      this.rejectInitializing()\n    }\n    throw new Error(`Error: cannot connect to Postgres: ${err.message}`)\n  }\n\n  await this.createExtensions()\n\n  await assertOperatorHandlerExtensionsInstalled({\n    drizzle: this.drizzle,\n    operatorHandlers: this.operatorHandlers,\n  })\n\n  // Only push schema if not in production\n  if (\n    process.env.NODE_ENV !== 'production' &&\n    process.env.PAYLOAD_MIGRATING !== 'true' &&\n    this.push !== false\n  ) {\n    await pushDevSchema(this as unknown as DrizzleAdapter)\n  }\n","sourceCodeStart":95,"sourceCodeEnd":131,"githubUrl":"https://github.com/payloadcms/payload/blob/00c58b35c0ed348ddc22daabf467b139727214fd/packages/db-postgres/src/connect.ts#L95-L131","documentation":"Thrown by the Postgres (db-postgres) adapter's `connect` after the underlying connection attempt rejects. The adapter logs the detail, calls `rejectInitializing` to fail the init promise, then re-throws a wrapped Error so that `payload.init()` rejects and the app fails fast rather than running without a DB.","triggerScenarios":"`payload.init()` cannot reach Postgres: invalid connection string/pool config, wrong host/port, bad credentials, the database does not exist, SSL/TLS misconfiguration, or a network/firewall block.","commonSituations":"Wrong/missing `pool`/`poolURL`/`DATABASE_URL` env var; rotated credentials; Postgres service not running; security group/firewall blocks port 5432; SSL required by server but not configured; DNS resolution failure.","solutions":["Verify the connection string and credentials with `psql` from the same host.","Confirm Postgres is running and reachable: `nc -zv <host> 5432`.","Ensure env vars are actually loaded into the process.","Match SSL settings (`ssl: true`/`sslmode`) to what the server requires.","Confirm the target database exists and the user has CONNECT privileges."],"exampleFix":"// before\npayload.init({ secret, db: postgresAdapter({ pool: { connectionString: process.env.DATABASE_URL } }) }) // DATABASE_URL unset\n// after\npayload.init({ secret, db: postgresAdapter({ pool: { connectionString: process.env.DATABASE_URL } }) })\n// .env: DATABASE_URL=postgres://user:pass@host:5432/db","handlingStrategy":"retry","validationCode":"async function assertPostgresReachable(connectionString, timeoutMs = 5000) {\n  const u = new URL(connectionString)\n  const ok = await probeTcp(u.hostname, Number(u.port || 5432), timeoutMs)\n  if (!ok) throw new Error(`Postgres unreachable at ${u.host}`)\n}","typeGuard":"const looksLikeValidPostgresUrl = (s) => {\n  try { const u = new URL(s); return u.protocol === 'postgres:' || u.protocol === 'postgresql:' }\n  catch { return false }\n}","tryCatchPattern":"try { await payload.init() }\ncatch (e) { if (/cannot connect to Postgres/.test(e.message)) { await backoffRetry(() => payload.init()) } else throw e }","preventionTips":["Validate the connection string is present and well-formed at boot.","Keep Postgres credentials in env vars managed by a secret store.","Verify network/SG rules allow egress to port 5432 from the app host.","Add a startup readiness check that opens a real connection before serving traffic."],"tags":["postgres","connection","startup","network","config"],"backgroundTag":null,"analyzedSha":"00c58b35c0ed348ddc22daabf467b139727214fd","analyzedAt":"2026-08-12T20:45:03.758Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}