{"record":{"id":"07058541c8c434ee","repo":"payloadcms/payload","slug":"error-cannot-connect-to-postgres-err-message-070585","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-vercel-postgres/src/connect.ts","lineNumber":95,"sourceCode":"        `${err.message.charAt(0).toUpperCase() + err.message.slice(1)}, creating...`,\n      )\n      const isCreated = await this.createDatabase()\n\n      if (isCreated) {\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":77,"sourceCodeEnd":113,"githubUrl":"https://github.com/payloadcms/payload/blob/00c58b35c0ed348ddc22daabf467b139727214fd/packages/db-vercel-postgres/src/connect.ts#L77-L113","documentation":"Same shape as the db-postgres connect error, but thrown by the Vercel Postgres (db-vercel-postgres) adapter. The connection attempt rejects, the adapter logs, rejects init, and re-throws a wrapped Error so `payload.init()` fails fast.","triggerScenarios":"The Vercel Postgres connection cannot be established: env vars (`POSTGRES_URL` / `POSTGRES_PRISMA_URL` etc.) missing or wrong, the Vercel project isn't linked to a Postgres store, the store is paused/deleted, or there is a network/egress issue.","commonSituations":"Env var not exposed to the function runtime; wrong Vercel env scope (Preview vs Production); Vercel DB paused or deleted; egress/IP restrictions; connection string copied for the wrong environment.","solutions":["Confirm a Vercel Postgres store exists and is linked to the project.","Verify the env vars are present in the runtime (log `process.env.POSTGRES_URL` keys, not values).","Check the Vercel dashboard for the DB status (active/paused).","Validate connectivity with a raw query tool from the same environment.","Match the connection string to the correct environment scope."],"exampleFix":"// before\nvercelPostgresAdapter({ pool: { connectionString: process.env.POSTGRES_URL } }) // var not in scope\n// after\n// Vercel: mark POSTGRES_URL as available to Preview+Production+Development\nvercelPostgresAdapter({ pool: { connectionString: process.env.POSTGRES_URL } })","handlingStrategy":"validation","validationCode":"function assertVercelPgEnv() {\n  const keys = ['POSTGRES_URL', 'POSTGRES_PRISMA_URL']\n  if (!keys.some(k => process.env[k])) throw new Error('Vercel Postgres env vars missing')\n}","typeGuard":"const hasVercelPgEnv = () =>\n  Boolean(process.env.POSTGRES_URL || process.env.POSTGRES_PRISMA_URL)","tryCatchPattern":"try { await payload.init() }\ncatch (e) { if (/cannot connect to Postgres/.test(e.message)) { await verifyVercelDbAndRetry() } else throw e }","preventionTips":["Mark Vercel Postgres env vars available to all environments that need them.","Confirm the Vercel Postgres store is active (not paused/deleted).","Use environment-scoped connection strings.","Add a boot-time check that the env vars are present before init."],"tags":["postgres","vercel","connection","startup","serverless","config"],"backgroundTag":null,"analyzedSha":"00c58b35c0ed348ddc22daabf467b139727214fd","analyzedAt":"2026-08-12T20:45:03.758Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}