Why medusa db:migrate Hangs Forever — and How to Diagnose It

I have watched this eat an afternoon more than once: the migration works perfectly on a laptop, then stops dead the first time it runs inside a container, and the only difference is the hostname in a connection string. I am Manoj, commerce and ERP implementation lead at Mith Tech in Bengaluru, and we run Medusa deployments where the migration step is the last thing anyone wants to be guessing about.

What the hang actually looks like

The log order matters, because it is the strongest clue you get. In packages/medusa/src/commands/db/migrate.ts the sequence is: Running migrations..., then ensureMigrationsTable() — which logs Creating migrations table 'mikro_orm_migrations'... and Migrations table created successfully — then runModulesMigrations(...), then Migrations completed.

So a hang that always appears to start immediately after the migrations table is created is not a coincidence. The table creation uses the framework's already-established Postgres connection, which worked. The module migrations then open new connections through a different code path — the one that applies the SSL classification. The framework connection succeeded; the module connections never did.

Two very different bugs land you at that same silent screen. The diagnoser separates them:

# Prove it in 10 seconds — no Medusa involved.
psql "$DATABASE_URL" -c "SHOW ssl;"    # "off" means the forced-SSL branch will stall

Mode A — forced SSL on a non-localhost host (confirmed)

This is the common one, and it is fully understood. In packages/core/utils/src/modules-sdk/load-module-database-config.ts, getDefaultDriverOptions() decides your SSL settings by regex-matching the connection URL:

function getDefaultDriverOptions(clientUrl) {
  const localOptions  = { connection: { ssl: false } }
  const remoteOptions = { connection: { ssl: { rejectUnauthorized: false } } }

  if (clientUrl) {
    return clientUrl.match(
      /localhost|127\.0\.0\.1|ssl_mode=(disable|false)|sslmode=(disable)/i
    ) ? localOptions : remoteOptions
  }
  return process.env.NODE_ENV?.match(/prod/i) ? remoteOptions
       : process.env.NODE_ENV?.match(/dev/i)  ? localOptions
       : {}
}

Read that carefully. postgres://medusa:medusa@postgres:5432/medusa — a perfectly ordinary Docker Compose service name — does not match, so it takes the remote branch and attempts TLS. A stock postgres:16-alpine has no TLS configured. The negotiation goes nowhere.

Under normal circumstances a connection that cannot be established produces an error. Here it does not, because packages/core/utils/src/modules-sdk/create-pg-connection.ts sets pool: { propagateCreateError: false }. That is a knex/tarn option meaning a pool-creation failure is not propagated to the caller — the raw() call simply stays pending. There is no rejection to catch and nothing to log.

The orchestration on top makes the stall total rather than partial. medusa-app.ts creates a dedicated lock connection with pool: { min: 1, max: 1 }, and for each module opens a transaction that takes pg_advisory_xact_lock(hashtext('db-module-migration:<module>')) before running that module's migrations, with DB_MIGRATION_CONCURRENCY defaulting to 1. One connection, one lock, one module at a time. When the connection never comes up, the whole run stops with zero output rather than failing on one module and continuing.

Medusa's maintainer confirmed the classification directly when closing issue #15987: the issue happens when the URL is not localhost, because that is automatically treated as remote. Issue #15658 is the underlying root-cause report, complete with the source-level regex and the version matrix — and it notes something useful: on 2.14.0 this failed loudly with The server does not support SSL connections, and regressed into a silent hang in 2.15.x.

The fix, and what the default would have done to you

The fix is one block in medusa-config.ts. databaseDriverOptions bypasses the host classification entirely rather than trying to satisfy it — which matters, because ?sslmode=disable in the URL is unreliable. Medusa rebuilds the connection URL from discrete host config in places, dropping the query string, so the marker does not survive into every module path.

// medusa-config.ts
import { defineConfig } from "@medusajs/framework/utils"

export default defineConfig({
  projectConfig: {
    databaseUrl: process.env.DATABASE_URL, // postgres://medusa:medusa@postgres:5432/medusa
      databaseDriverOptions: {
        connection: { ssl: false },
      },
  },
})

The reporter on #15987 A/B-tested exactly this on a minimal reproduction — node:22-slim, Medusa 2.17.2, postgres:16-alpine reached by Docker service name. Baseline: hangs forever after the migrations table is created. With only ssl: false added and the service name left untouched in DATABASE_URL: completes, exit code 0. Medusa's own Docker installation guide documents the slightly different { ssl: false, sslmode: "disable" } form in its Disable SSL for PostgreSQL Connection section; both work.

Mode B — the aarch64 deadlock, still open

Now the part almost nobody writes down honestly. Issue #16011 reports that on aarch64 Linux — an Oracle Cloud Ampere A1 box, Ubuntu 24.04 — medusa db:migrate deadlocks, while the identical project migrating the identical database from x86_64 (GitHub Actions ubuntu-latest over an SSH tunnel, and x86_64 macOS) completes fine.

What the reporter has ruled out, on his own hardware: Node 20.18, 20.20 and 22 all hang. node:20-slim, node:22-slim, node:20 and node:20-alpine all hang. It reproduces both inside Docker and on the bare host, so it is not a container issue. seccomp=unconfined, UV_USE_IO_URING=0, Docker embedded DNS (tested by direct IP), MTU, telemetry, --skip-links, --skip-scripts and --concurrency 1 made no difference. And critically: databaseDriverOptions.connection.ssl = false did not fix it either. He tested the maintainer's exact snippet and got identical behaviour, EXIT=124 under timeout 120 both runs. Meanwhile medusa start runs fine on the same box with the same DATABASE_URL, serving production traffic. Only the migrator deadlocks.

His own investigation — and I want to be precise that this is the reporter's hypothesis, not Medusa's conclusion — traces an async_hooks chain from runMigrations through executeWithConcurrency down to lockKnex.transaction() and a Promise.then in knex's transaction machinery that never resolves. A Node diagnostic report at hang time shows an idle event loop, no timers, and a single referenced active handle: one idle Postgres TCP socket. On the Postgres side that connection sits state = idle, wait_event = ClientRead.

Medusa's position, stated plainly: the SSL explanation was proposed twice, disproved on that box both times, and the 10-second guard shipped with the explicit note that the version does not fix the issue because it is not clear what the issue is. As of this writing the issue is open, labelled requires-team, with one reporter and no independent reproduction in the tracker.

Two consequences you should carry away. First, on 2.18.0+ the ARM64 case now produces an error that says the timeout "usually indicates an incorrect database URL or an SSL configuration issue" — which in this specific case is wrong, since the migrator had already connected and created the table. Do not let that message send you down the SSL path a second time. Second, the only thing reported to work is running the migration from an x86_64 machine against the same database, then deploying to the ARM host. That is the reporter's production workaround today.

The diagnosis playbook

Before you change any configuration, find out where the process actually stopped. These are the four places worth looking, in the order that narrows fastest.

-- What is every backend on this database actually doing?
SELECT pid,
       state,
       wait_event_type,
       wait_event,
       backend_start,
       xact_start,
       state_change,
       now() - state_change AS in_state_for,
       client_addr,
       application_name,
       left(query, 120) AS query
FROM pg_stat_activity
WHERE datname = current_database()
  AND pid <> pg_backend_pid()
ORDER BY state_change;

-- Medusa takes pg_advisory_xact_lock(hashtext('db-module-migration:<module>'))
-- per module, so a zombie migrator can still be holding one.
SELECT l.pid, l.locktype, l.mode, l.granted, l.objid, l.classid,
       a.state, a.wait_event_type, a.wait_event, left(a.query, 100) AS query
FROM pg_locks l
LEFT JOIN pg_stat_activity a USING (pid)
WHERE l.locktype = 'advisory'
ORDER BY l.granted, l.pid;

-- Classic blocking, if anything is genuinely blocked.
SELECT pid, pg_blocking_pids(pid) AS blocked_by, state,
       wait_event_type, wait_event, left(query,100)
FROM pg_stat_activity
WHERE cardinality(pg_blocking_pids(pid)) > 0;

-- Destructive: aborts that transaction. Advisory xact locks release with it.
-- SELECT pg_terminate_backend(<pid>);

Recovering a migration that died halfway

Medusa's migrator is not wrapped in one giant transaction across all modules. Each module runs inside its own lockKnex.transaction() with a transaction-scoped advisory lock, executed serially. In practice that means completed modules are committed and recorded in mikro_orm_migrations, and the module that was interrupted rolled back with its transaction — its DDL was inside it. A killed migrator is usually not a corrupt state. Verify that before you start deleting rows.

SELECT id, name, executed_at FROM mikro_orm_migrations ORDER BY id DESC LIMIT 30;
SELECT count(*) FROM mikro_orm_migrations;
SELECT to_regclass('public.script_migrations');
SELECT id, script_name, created_at, finished_at
FROM script_migrations WHERE finished_at IS NULL;

Two things worth stating outright. Never TRUNCATE mikro_orm_migrations on a database with data in it — Medusa will replay every migration from zero and the first CREATE TABLE against an object that already exists will abort the run. And there is no db:reset command; the supported reset per Medusa's own CLI reference is to drop the database manually and run npx medusa db:setup --db <db_name>.

Which version changes what

One undocumented escape hatch worth knowing, confirmed in the 2.18.0 source and its unit test: MEDUSA_DB_MIGRATION_CONNECTION_TIMEOUT overrides the new 10-second migration connection guard. If you have a genuinely slow-to-accept database and the guard is firing on a migration that would have succeeded, that is the knob.

A migration that hangs with no error is not a mysterious failure — it is a connection that never rejected, sitting behind a pool option that was chosen for a different purpose. Check the hostname in your connection string and whether the database on the other end speaks TLS, and you will resolve most of these in a minute. If you have ruled that out and you are on aarch64, you are in the open issue, and the honest answer today is to migrate from an x86_64 machine and watch #16011.