payloadcms/payload · critical · Error

Error: cannot connect to Postgres: ${err.message}

Error message

Error: cannot connect to Postgres: ${err.message}

What it means

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.

Source

Thrown at packages/db-vercel-postgres/src/connect.ts:95

        `${err.message.charAt(0).toUpperCase() + err.message.slice(1)}, creating...`,
      )
      const isCreated = await this.createDatabase()

      if (isCreated) {
        await this.connect?.(options)
        return
      }
    } else {
      this.payload.logger.error({
        err,
        msg: `Error: cannot connect to Postgres. Details: ${err.message}`,
      })
    }

    if (typeof this.rejectInitializing === 'function') {
      this.rejectInitializing()
    }
    throw new Error(`Error: cannot connect to Postgres: ${err.message}`)
  }

  await this.createExtensions()

  await assertOperatorHandlerExtensionsInstalled({
    drizzle: this.drizzle,
    operatorHandlers: this.operatorHandlers,
  })

  // Only push schema if not in production
  if (
    process.env.NODE_ENV !== 'production' &&
    process.env.PAYLOAD_MIGRATING !== 'true' &&
    this.push !== false
  ) {
    await pushDevSchema(this as unknown as DrizzleAdapter)
  }

View on GitHub (pinned to 00c58b35c0)

Solutions

1. Confirm a Vercel Postgres store exists and is linked to the project.
2. Verify the env vars are present in the runtime (log `process.env.POSTGRES_URL` keys, not values).
3. Check the Vercel dashboard for the DB status (active/paused).
4. Validate connectivity with a raw query tool from the same environment.
5. Match the connection string to the correct environment scope.

Example fix

// before
vercelPostgresAdapter({ pool: { connectionString: process.env.POSTGRES_URL } }) // var not in scope
// after
// Vercel: mark POSTGRES_URL as available to Preview+Production+Development
vercelPostgresAdapter({ pool: { connectionString: process.env.POSTGRES_URL } })

function assertVercelPgEnv() {
  const keys = ['POSTGRES_URL', 'POSTGRES_PRISMA_URL']
  if (!keys.some(k => process.env[k])) throw new Error('Vercel Postgres env vars missing')
}

const hasVercelPgEnv = () =>
  Boolean(process.env.POSTGRES_URL || process.env.POSTGRES_PRISMA_URL)

try { await payload.init() }
catch (e) { if (/cannot connect to Postgres/.test(e.message)) { await verifyVercelDbAndRetry() } else throw e }

When it happens

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

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

Related errors

• Error: cannot connect to Postgres: ${err.message}
• beginTransaction called while no connection to the database
• Error: cannot connect to SQLite: ${message}
• Operator handler "${handler.name}" requires the "${extension
• Error: missing MongoDB connection URL.

AI-assisted analysis of payloadcms/payload@00c58b35c0 (2026-08-12). Data as JSON: /api/errors/07058541c8c434ee. Report an issue: GitHub.