medusajs/medusa · critical · Error

The specified PostgreSQL database does not exist. Please cre

Error message

The specified PostgreSQL database does not exist. Please create it and try again.${EOL}${err.message}

What it means

Maps PostgreSQL error code 3D000 (databaseDoesNotExist) to a friendly message. Medusa throws it on startup or during migrations when the database named in the connection string does not exist on the server.

Source

Thrown at packages/core/utils/src/common/handle-postgres-database-error.ts:13

import { EOL } from "os"

export const DatabaseErrorCode = {
  databaseDoesNotExist: "3D000",
  connectionFailure: "ECONNREFUSED",
  wrongCredentials: "28000",
  notFound: "ENOTFOUND",
  migrationMissing: "42P01",
}

export function handlePostgresDatabaseError(err: any): never {
  if (DatabaseErrorCode.databaseDoesNotExist === err.code) {
    throw new Error(
      `The specified PostgreSQL database does not exist. Please create it and try again.${EOL}${err.message}`
    )
  }

  if (DatabaseErrorCode.connectionFailure === err.code) {
    throw new Error(
      `Failed to establish a connection to PostgreSQL. Please ensure the following is true and try again:
      - You have a PostgreSQL database running
      - You have passed the correct credentials in medusa-config.js
      - You have formatted the database connection string correctly. See below:
      "postgres://[username]:[password]@[host]:[port]/[db_name]" - If there is no password, you can omit it from the connection string
      ${EOL}
      ${err.message}`
    )
  }

  if (DatabaseErrorCode.wrongCredentials === err.code) {
    throw new Error(

View on GitHub (pinned to 5e06e544a2)

Solutions

  1. Create the database: `createdb medusa-store` or `psql -c 'CREATE DATABASE "medusa-store";'`
  2. Fix the database name in DATABASE_URL / medusa-config db config
  3. In Docker/CI, ensure the postgres service and init step run before medusa

Example fix

# before: DATABASE_URL=postgres://user:pass@localhost:5432/medusa_store
createdb medusa_store
# after: DATABASE_URL=postgres://user:pass@localhost:5432/medusa_store
Defensive patterns

Strategy: validation

Validate before calling

const { Client } = require('pg')
const c = new Client({ connectionString: process.env.DATABASE_URL, connectionTimeoutMillis: 3000 })
const db = new URL(process.env.DATABASE_URL).pathname.slice(1)
await c.connect(); const r = await c.query('SELECT 1 FROM pg_database WHERE datname=$1', [db]); await c.end()
if (!r.rowCount) await new Client({ connectionString: adminUrl }).query(`CREATE DATABASE "${db}"`)

Try / catch

try { await bootstrap() } catch (e) { if (/database does not exist/i.test(e.message)) { await createDb(); await bootstrap() } else throw e }

Prevention

When it happens

Trigger: DATABASE_URL/medusa-config database config pointing at a database that was never created, e.g. postgres://user:pass@localhost:5432/medusa-store before running createdb.

Common situations: Fresh environments, CI without a provisioning step, typos in the db name, or after dropping/recreating environments.

Related errors

AI-assisted analysis of medusajs/medusa@5e06e544a2 (2026-08-27). Data as JSON: /api/errors/d249d9d099b0bb2d. Report an issue: GitHub.