medusajs/medusa · critical · Error

Migrations missing. Please run 'medusa migrations run' and t

Error message

Migrations missing. Please run 'medusa migrations run' and try again.

What it means

Maps PostgreSQL error 42P01 (undefined_table). Medusa interprets it as the schema not being migrated: the tables the code expects do not exist yet.

Source

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

      ${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

Run `npx medusa db migrate` (or `medusa migrations run`) against the same DATABASE_URL used at runtime
Verify all module migrations ran (medusa db migrate runs module migrations)
In CI add the migrate step before starting the app

Example fix

# before
medusa start
# after
medusa db migrate && medusa start

Defensive patterns

Strategy: fallback

Validate before calling

const { Client } = require('pg')
const c = new Client({ connectionString: process.env.DATABASE_URL }); await c.connect()
const { rows } = await c.query("SELECT to_regclass('public.product') AS t"); await c.end()
if (!rows[0].t) await exec('npx medusa db migrate')

Try / catch

try { await start() } catch (e) { if (/Migrations missing/.test(e.message)) { await run('medusa db migrate'); await start() } else throw e }

Prevention

Always run migrations as a release/CI step before start
Use the same DATABASE_URL for migrate and start

When it happens

Trigger: Running the server, admin, or integration tests against a fresh/empty database before running migrations; or migrations that ran against a different database than the runtime is using.

Common situations: New environments, after dropping the db, CI pipelines skipping the migration step, or DATABASE_URL differing between migrate and start.

Related errors

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