{"record":{"id":"fc78c7d6a26b4e8f","repo":"medusajs/medusa","slug":"the-specified-connection-string-for-your-postgresq","errorCode":null,"errorMessage":"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}","messagePattern":"The specified connection string for your PostgreSQL database might have illegal characters\\. Please check that it only contains allowed characters \\[a-zA-Z0-9\\](.+?)(.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"packages/core/utils/src/common/handle-postgres-database-error.ts","lineNumber":37,"sourceCode":"    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(\n      `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}`\n    )\n  }\n\n  if (DatabaseErrorCode.migrationMissing === err.code) {\n    throw new Error(\n      `Migrations missing. Please run 'medusa migrations run' and try again.`\n    )\n  }\n\n  throw err\n}\n","sourceCodeStart":19,"sourceCodeEnd":50,"githubUrl":"https://github.com/medusajs/medusa/blob/5e06e544a296b9033f20f71f11c559f81a0e5739/packages/core/utils/src/common/handle-postgres-database-error.ts#L19-L50","documentation":"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.","triggerScenarios":"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.","commonSituations":"ENV quoting issues (e.g. DATABASE_URL='... quoted in file'), docker service names vs localhost, trailing whitespace from copy-paste.","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"],"exampleFix":"# before (stray quote)\nDATABASE_URL=\"'postgres://u:p@db:5432/store'\"\n# after\nDATABASE_URL=postgres://u:p@db:5432/store","handlingStrategy":"validation","validationCode":"const url = process.env.DATABASE_URL.trim()\nif (/[^\\w:@/.\\-%~]/.test(url.replace(/^postgres(ql)?:\\/\\//, ''))) throw new Error('illegal chars in DATABASE_URL')","typeGuard":"const isSafeConnString = (s: string) => /^[\\w:@/.\\-%~]+$/.test(s.trim())","tryCatchPattern":null,"preventionTips":["Trim env values; avoid quoting inside .env values","Use docker service names, not localhost, from containers"],"tags":["postgres","connection-string","dns","config"],"backgroundTag":"invalid-connection-string","analyzedSha":"5e06e544a296b9033f20f71f11c559f81a0e5739","analyzedAt":"2026-08-27T07:24:39.599Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}