medusajs/medusa · critical · Error

The specified connection string for your PostgreSQL database

Error message

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}

What it means

Maps ENOTFOUND-style errors where hostname resolution failed, and suggests the connection string may contain illegal characters. In practice it fires when the host cannot be resolved to an address.

Source

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

    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

Print and inspect DATABASE_URL for stray quotes/spaces; trim it
Use the correct host (docker service name, or host.docker.internal from containers)
Ensure only allowed characters and proper URL encoding are used

Example fix

# before (stray quote)
DATABASE_URL="'postgres://u:p@db:5432/store'"
# after
DATABASE_URL=postgres://u:p@db:5432/store

Defensive patterns

Strategy: validation

Validate before calling

const url = process.env.DATABASE_URL.trim()
if (/[^\w:@/.\-%~]/.test(url.replace(/^postgres(ql)?:\/\//, ''))) throw new Error('illegal chars in DATABASE_URL')

Type guard

const isSafeConnString = (s: string) => /^[\w:@/.\-%~]+$/.test(s.trim())

Prevention

Trim env values; avoid quoting inside .env values
Use docker service names, not localhost, from containers

When it happens

Trigger: Misspelled host, leftover quotes/space/newline in DATABASE_URL, using localhost inside a container that can't resolve it, or a connection string with unescaped characters breaking parsing.

Common situations: ENV quoting issues (e.g. DATABASE_URL='... quoted in file'), docker service names vs localhost, trailing whitespace from copy-paste.

Related errors

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