{"record":{"id":"d249d9d099b0bb2d","repo":"medusajs/medusa","slug":"the-specified-postgresql-database-does-not-exist","errorCode":null,"errorMessage":"The specified PostgreSQL database does not exist. Please create it and try again.${EOL}${err.message}","messagePattern":"The specified PostgreSQL database does not exist\\. Please create it and try again\\.(.+?)(.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"packages/core/utils/src/common/handle-postgres-database-error.ts","lineNumber":13,"sourceCode":"import { EOL } from \"os\"\n\nexport const DatabaseErrorCode = {\n  databaseDoesNotExist: \"3D000\",\n  connectionFailure: \"ECONNREFUSED\",\n  wrongCredentials: \"28000\",\n  notFound: \"ENOTFOUND\",\n  migrationMissing: \"42P01\",\n}\n\nexport function handlePostgresDatabaseError(err: any): never {\n  if (DatabaseErrorCode.databaseDoesNotExist === err.code) {\n    throw new Error(\n      `The specified PostgreSQL database does not exist. Please create it and try again.${EOL}${err.message}`\n    )\n  }\n\n  if (DatabaseErrorCode.connectionFailure === err.code) {\n    throw new Error(\n      `Failed to establish a connection to PostgreSQL. Please ensure the following is true and try again:\n      - You have a PostgreSQL database running\n      - You have passed the correct credentials in medusa-config.js\n      - You have formatted the database connection string correctly. See below:\n      \"postgres://[username]:[password]@[host]:[port]/[db_name]\" - If there is no password, you can omit it from the connection string\n      ${EOL}\n      ${err.message}`\n    )\n  }\n\n  if (DatabaseErrorCode.wrongCredentials === err.code) {\n    throw new Error(","sourceCodeStart":1,"sourceCodeEnd":31,"githubUrl":"https://github.com/medusajs/medusa/blob/5e06e544a296b9033f20f71f11c559f81a0e5739/packages/core/utils/src/common/handle-postgres-database-error.ts#L1-L31","documentation":"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.","triggerScenarios":"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.","commonSituations":"Fresh environments, CI without a provisioning step, typos in the db name, or after dropping/recreating environments.","solutions":["Create the database: `createdb medusa-store` or `psql -c 'CREATE DATABASE \"medusa-store\";'`","Fix the database name in DATABASE_URL / medusa-config db config","In Docker/CI, ensure the postgres service and init step run before medusa"],"exampleFix":"# before: DATABASE_URL=postgres://user:pass@localhost:5432/medusa_store\ncreatedb medusa_store\n# after: DATABASE_URL=postgres://user:pass@localhost:5432/medusa_store","handlingStrategy":"validation","validationCode":"const { Client } = require('pg')\nconst c = new Client({ connectionString: process.env.DATABASE_URL, connectionTimeoutMillis: 3000 })\nconst db = new URL(process.env.DATABASE_URL).pathname.slice(1)\nawait c.connect(); const r = await c.query('SELECT 1 FROM pg_database WHERE datname=$1', [db]); await c.end()\nif (!r.rowCount) await new Client({ connectionString: adminUrl }).query(`CREATE DATABASE \"${db}\"`)","typeGuard":null,"tryCatchPattern":"try { await bootstrap() } catch (e) { if (/database does not exist/i.test(e.message)) { await createDb(); await bootstrap() } else throw e }","preventionTips":["Provision the database in deployment scripts/entrypoints","Add a db-exists preflight in CI jobs"],"tags":["postgres","database","connection","startup"],"backgroundTag":"database-does-not-exist","analyzedSha":"5e06e544a296b9033f20f71f11c559f81a0e5739","analyzedAt":"2026-08-27T07:24:39.599Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}