{"record":{"id":"08168cb78009666d","repo":"medusajs/medusa","slug":"failed-to-establish-a-connection-to-postgresql-pl","errorCode":null,"errorMessage":"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}","messagePattern":"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      (.+?)\n      (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"packages/core/utils/src/common/handle-postgres-database-error.ts","lineNumber":19,"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(\n      `The specified credentials does not exists for the specified PostgreSQL database.${EOL}${err.message}`\n    )\n  }\n\n  if (DatabaseErrorCode.notFound === err.code) {\n    throw new Error(","sourceCodeStart":1,"sourceCodeEnd":37,"githubUrl":"https://github.com/medusajs/medusa/blob/5e06e544a296b9033f20f71f11c559f81a0e5739/packages/core/utils/src/common/handle-postgres-database-error.ts#L1-L37","documentation":"Maps PostgreSQL connection-failure errors (e.g. ECONNREFUSED) into a checklist message. It means Medusa could not open a TCP connection to the Postgres server at all.","triggerScenarios":"Postgres not running, wrong host/port in DATABASE_URL, firewall/DNS issues, or docker-compose where the app starts before the db service is ready.","commonSituations":"Local dev without postgres started, wrong port (5433 vs 5432), container networking (localhost vs service name), or transient startup races in CI.","solutions":["Start PostgreSQL and verify with `pg_isready -h host -p port`","Correct host/port/credentials in the connection string","Add retry/wait-for-db (depends_on with condition: service_healthy) in docker-compose"],"exampleFix":"# docker-compose before\nservices:\n  api:\n    depends_on: [db]\n# after\nservices:\n  api:\n    depends_on:\n      db: { condition: service_healthy }\n  db:\n    healthcheck: { test: [\"CMD\",\"pg_isready\"], interval: 5s }","handlingStrategy":"retry","validationCode":"// preflight\nconst net = require('net')\nawait new Promise((res, rej) => { const s = net.connect(port, host, () => (s.destroy(), res()))\n  s.on('error', rej) })","typeGuard":null,"tryCatchPattern":"for (let i = 0; i < 5; i++) { try { return await connect() } catch (e) { if (/Failed to establish a connection/.test(e.message)) await sleep(2000 * (i + 1)); else throw e } } throw lastError","preventionTips":["Use docker-compose healthchecks with condition: service_healthy","Keep host/port in one env var and document it"],"tags":["postgres","connection","network","docker"],"backgroundTag":"connection-refused","analyzedSha":"5e06e544a296b9033f20f71f11c559f81a0e5739","analyzedAt":"2026-08-27T07:24:39.599Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}