medusajs/medusa · critical · Error

The specified credentials does not exists for the specified

Error message

The specified credentials does not exists for the specified PostgreSQL database.${EOL}${err.message}

What it means

Maps PostgreSQL authentication failures (e.g. 28P01 password authentication failed) to a clear message: the server was reached but the username/password pair was rejected.

Source

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

    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(
      `The specified credentials does not exists for the specified PostgreSQL database.${EOL}${err.message}`
    )
  }

  if (DatabaseErrorCode.notFound === err.code) {
    throw new Error(
      `The specified connection string for your PostgreSQL database might have illegal characters. Please check that it only contains allowed characters [a-zA-Z0-9]${EOL}${err.message}`
    )
  }

  if (DatabaseErrorCode.migrationMissing === err.code) {
    throw new Error(
      `Migrations missing. Please run 'medusa migrations run' and try again.`
    )
  }

  throw err
}

View on GitHub (pinned to 5e06e544a2)

Solutions

  1. Verify username/password against the Postgres server (psql connect test)
  2. URL-encode special characters in the password inside DATABASE_URL
  3. Check pg_hba.conf auth method and the user exists

Example fix

# before (password with @ breaks parsing)
DATABASE_URL=postgres://user:p@ss@localhost:5432/db
# after
DATABASE_URL=postgres://user:p%40ss@localhost:5432/db
Defensive patterns

Strategy: try-catch

Validate before calling

// encode password properly
const u = new URL('postgres://localhost:5432/db')
u.username = process.env.PGUSER; u.password = process.env.PGPASSWORD
process.env.DATABASE_URL = u.toString()

Try / catch

try { await connect() } catch (e) { if (/credentials does not exist|password authentication/i.test(e.message)) fail fast with a config checklist; else throw e }

Prevention

When it happens

Trigger: Wrong POSTGRES_PASSWORD/DATABASE_URL password, user doesn't exist, or pg_hba.conf requiring a different auth method.

Common situations: Rotated credentials, env var mismatch between .env and docker-compose, special characters in the password not URL-encoded in the connection string.

Related errors

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