Failed to setup database; install PostgresQL or make sure to

Error message

Failed to setup database; install PostgresQL or make sure to manage your database connection manually

What it means

During `medusa new`, the CLI attempts to create and bootstrap the project database (create DB, run migrations). If that setup fails (usually because PostgreSQL is not installed/running or credentials are wrong), it warns that database setup was skipped; the project is created but the DB must be configured manually.

Source

Thrown at packages/cli/medusa-cli/src/commands/new.ts:281

export const setupDB = async (dbName, dbCreds = {}) => {
  const credentials = Object.assign({}, defaultDBCreds, dbCreds)

  const dbActivity = reporter.activity(`Setting up database "${dbName}"...`)
  await createDatabase(dbName, credentials)
    .then(() => {
      reporter.success(dbActivity, `Created database "${dbName}"`)
    })
    .catch((err) => {
      // Postgres raises 42P04 (duplicate_database) when the database already exists
      if (err.code === "42P04") {
        reporter.success(
          dbActivity,
          `Database ${dbName} already exists; skipping setup`
        )
      } else {
        reporter.failure(dbActivity, `Skipping database setup.`)
        reporter.warn(
          `Failed to setup database; install PostgresQL or make sure to manage your database connection manually`
        )
        console.error(err)
      }
    })
}

const setupEnvVars = async (rootPath, dbName, dbCreds = {}) => {
  const templatePath = sysPath.join(rootPath, ".env.template")
  const destination = sysPath.join(rootPath, ".env")
  if (existsSync(templatePath)) {
    fs.renameSync(templatePath, destination)
  }

  const credentials = Object.assign({}, defaultDBCreds, dbCreds)
  let dbUrl = ""
  if (
    credentials.user !== defaultDBCreds.user ||

View on GitHub (pinned to 5e06e544a2)

Solutions

Install and start PostgreSQL (or run it via Docker: docker run -d -p 5432:5432 -e POSTGRES_PASSWORD=postgres postgres)
Set correct DB env vars (DATABASE_URL or PGHOST/PGUSER/PGPASSWORD) and re-run migrations: medusa db migrate
Seed the database afterwards: medusa db seed

Example fix

# before
medusa new my-store

# after
docker run -d --name pg -p 5432:5432 -e POSTGRES_PASSWORD=postgres postgres
medusa new my-store
# then, if skipped:
cd my-store && medusa db migrate && medusa db seed

Defensive patterns

Strategy: fallback

Validate before calling

const { Client } = require("pg")
try {
  await new Client({ connectionstring: process.env.DATABASE_URL }).connect()
} catch (e) {
  throw new Error("Postgres unreachable — start it before running medusa new")
}

Prevention

Start/verify Postgres before running medusa new (pg_isready or docker ps)
Export correct DATABASE_URL / PG* env vars
After a skipped setup, run medusa db migrate and medusa db seed

When it happens

Trigger: medusa new executed on a machine where postgres is not installed, the server is stopped, or PGUSER/PGPASSWORD env vars do not permit creating a database.

Common situations: Fresh machine without Postgres; Docker postgres container not started; wrong DB connection env vars in the shell.

Related errors

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