[Bug]: `medusa db:migrate` hangs indefinitely right after creating the mikro_orm_migrations table

[nvdiffusionrun]

Package.json file

"name": "nvdiffusion-backend",
  "version": "0.0.1",
  "description": "Backend Medusa v2 de nvdiffusion.com.",
  "author": "Medusa (https://medusajs.com)",
  "license": "MIT",
  "keywords": [
    "sqlite",
    "postgres",
    "typescript",
    "ecommerce",
    "headless",
    "medusa"
  ],
  "scripts": {
    "build": "medusa build",
    "start": "medusa start",
    "dev": "medusa develop",
    "lint": "medusa lint",
    "test:integration:http": "TEST_TYPE=integration:http NODE_OPTIONS=--experimental-vm-modules jest --silent=false --runInBand --forceExit",
    "test:integration:modules": "TEST_TYPE=integration:modules NODE_OPTIONS=--experimental-vm-modules jest --silent=false --runInBand --forceExit",
    "test:unit": "TEST_TYPE=unit NODE_OPTIONS=--experimental-vm-modules jest --silent --runInBand --forceExit"
  },
  "dependencies": {
    "@medusajs/admin-sdk": "2.17.2",
    "@medusajs/admin-shared": "2.17.2",
    "@medusajs/caching": "2.17.2",
    "@medusajs/cli": "2.17.2",
    "@medusajs/dashboard": "2.17.2",
    "@medusajs/draft-order": "2.17.2",
    "@medusajs/framework": "2.17.2",
    "@medusajs/medusa": "2.17.2",
    "@medusajs/ui": "4.1.19",
    "@tanstack/react-query": "5.64.2",
    "react-i18next": "13.5.0",
    "react-router-dom": "6.30.3",
    "zod": "4.2.0"
  },
  "devDependencies": {
    "@medusajs/test-utils": "2.17.2",
    "@swc/core": "^1.7.28",
    "@swc/jest": "^0.2.36",
    "@types/jest": "^29.5.13",
    "@types/node": "^20.12.11",
    "@types/react": "^18.3.2",
    "@types/react-dom": "^18.2.25",
    "jest": "^29.7.0",
    "prop-types": "^15.8.1",
    "react": "^18.3.1",
    "react-dom": "^18.3.1",
    "ts-node": "^10.9.2",
    "typescript": "^5.6.2",
    "vite": "^5.4.14",
    "yalc": "^1.0.0-pre.53"
  },
  "engines": {
    "node": ">=20"
  },
  "packageManager": "npm@11.12.1"
}

Node.js version

v22.23.1 (also tested on v22-alpine, same result)

Database and its version

PostgreSQL 16.14

Operating system name and version

Reproduced inside Docker containers: node:22-alpine (musl) and node:22-slim (Debian/glibc). Same hang on both.

Browser name

N/A (backend CLI issue, no browser involved)

What happended?

import { loadEnv, defineConfig } from '@medusajs/framework/utils'

loadEnv(process.env.NODE_ENV || 'development', process.cwd())

module.exports = defineConfig({
projectConfig: {
databaseUrl: process.env.DATABASE_URL,
redisUrl: process.env.REDIS_URL,
workerMode: (process.env.MEDUSA_WORKER_MODE || "shared") as "shared" | "worker" | "server",
http: {
storeCors: process.env.STORE_CORS!,
adminCors: process.env.ADMIN_CORS!,
authCors: process.env.AUTH_CORS!,
jwtSecret: process.env.JWT_SECRET,
cookieSecret: process.env.COOKIE_SECRET,
}
}
})

Expected behavior

medusa db:migrate should run all pending migrations and exit, instead of hanging indefinitely

Actual behavior

the command hangs forever right after creating the mikro_orm_migrations table, 0% CPU, no error, no timeout

Link to reproduction repo

https://github.com/nvdiffusionrun/medusa-migrate-hang-repro

[medusa-os-bot]

Thanks for reporting this! We've labeled it as a bug and will investigate.

On Medusa 2.17.2, medusa db:migrate reportedly hangs indefinitely (0% CPU, no error) right after creating the mikro_orm_migrations table. Reported on Node 22 / PostgreSQL 16 in Docker (alpine and slim) with a linked reproduction repo. Standard config; root cause unclear, needs

[nvdiffusionrun]

Additional diagnostic: the hang appears to be specific to running the Medusa process inside a Docker container, not to the database, Redis, or the migrations themselves.

I ran the exact same scaffold (same package.json, same medusa-config.ts, same versions: @medusajs/medusa/cli/framework 2.17.2) with medusa db:migrate executed natively (Node 25.9.0 on macOS, outside any container), against Postgres 16 and Redis 7 running in plain Docker containers (just the data services, not the Medusa process itself).

Result: migrations completed successfully in ~15 seconds, no hang, exit code 0.

This was tested right after npm install --legacy-peer-deps (same flag used in the repro's Dockerfile), so dependency resolution is identical to the containerized case.

This suggests the root cause is tied to something about the Node process running inside a container (both node:22-slim and node:22-alpine hang, per the original report), rather than the migration logic, the @medusajs/draft-order module, or the database state. Hope this narrows things down.

[IndexOutOfMJ]

Could you try setting your db URL to "localhost" or any other domain or IP, just don't use the docker service name in the URL, that fixed it for me

[VictorKadup]

You could try to set this in your project config:

{
  ....
  databaseDriverOptions: { 
    connection: {       
      ssl: false,    
    },
  }
  ...
}

solved the problem for me.

[nvdiffusionrun]

@VictorKadup Confirmed, your workaround fixes it. Thank you!

I ran an A/B test on the minimal reproduction repo (https://github.com/nvdiffusionrun/medusa-migrate-hang-repro, node:22-slim, Medusa 2.17.2, postgres:16-alpine reached via the docker service name in DATABASE_URL):

• Baseline (unchanged config): hangs indefinitely right after "Migrations table created successfully", CPU near 0%, no further output after 5+ minutes.
• Same image and compose, with only this added to medusa-config.ts:

projectConfig: {
  // ...
  databaseDriverOptions: {
    connection: {
      ssl: false,
    },
  },
}

Result: the full migration runs to completion inside the container and exits with code 0.

Note that the DATABASE_URL still uses the docker service name (postgres) in the passing run, so in my case the ssl: false option alone is sufficient; switching the hostname was not needed (thanks @IndexOutOfMJ for the pointer, it clearly points to the same root area).

So the underlying issue seems to be that when ssl is left unspecified while running inside a container, the pg connection setup hangs silently instead of failing or falling back. A clean error (or a default of ssl: false when the server does not support TLS) would make this much easier to diagnose. Happy to test a fix on the repro if useful.

[shahednasser]

Hi @nvdiffusionrun we've confirmed that the issue happens when the URL is not localhost (as we automatically treat that as remote), so your fix is correct.

To improve the experience around this, we added a troubleshooting guide here, and we opened PR #16100 to show better error messages.