Bug: medusa db:migrate deadlocks (hangs) on aarch64/ARM64 Linux; works on x86_64

[aigoup]

Bug: medusa db:migrate deadlocks (hangs forever) on aarch64/ARM64 Linux; works on x86_64

Summary

npx medusa db:migrate hangs indefinitely at Running migrations... on ARM64 Linux hosts, but the identical project + database completes migrations normally on x86_64 (both x86_64 Linux and x86_64 macOS). The hang is an unresolved promise — the Node event loop goes fully idle with no pending I/O — inside the per-module migration transaction. It reproduces with a fresh create-medusa-app project (no custom modules), across Medusa 2.16.0 and 2.17.2, Node 20 and 22, and multiple base images.

Environment where it hangs

• Arch: aarch64 (ARM64) — Oracle Cloud Ampere A1, Ubuntu 24.04, kernel 6.8.0-1027-oracle
• Node: tested 20.18 / 20.20 / 22 (all hang)
• Medusa: 2.17.2 and 2.16.0 (all hang)
• Postgres 16, Redis 7 (also reproduces with REDIS_URL unset → "fake redis")
• Reproduces both in Docker and on the bare host (so not a container/sandbox issue)

Environment where it works

• x86_64 macOS (local) and x86_64 GitHub Actions ubuntu-latest — same repo, same DB, migrations complete in seconds.

Steps to reproduce

create-medusa-app app --version 2.17.2 --skip-db --no-browser
cd app/apps/backend
DATABASE_URL=postgres://user:pass@host:5432/db REDIS_URL= NODE_ENV=production \
  JWT_SECRET=x COOKIE_SECRET=x STORE_CORS=http://x ADMIN_CORS=http://x AUTH_CORS=http://x \
  npx medusa db:migrate

On ARM64: prints Running migrations... (and, on a fresh DB, Migrations table created successfully) then hangs forever. On x86_64: completes.

Diagnosis

• A minimal bare knex transaction using the exact same pattern Medusa uses — createPgConnection({ pool: { min:1, max:1 } }) + pg_advisory_xact_lock(hashtext(...)) inside knex.transaction() — works fine on the same ARM64 host. So knex/tarn/pg/advisory-locks are not the cause.
• An async_hooks trace of the hung process shows the never-resolving promise chain is:

  @medusajs/modules-sdk .../medusa-app.js runMigrations
    → applyMigration → @medusajs/utils executeWithConcurrency → executeNext (Promise.allSettled)
      → run (medusa-app.js) → lockKnex.transaction()
        → knex .../execution/transaction.js:79/85 (new Transaction, _evaluateContainer) → Promise.then  ← never resolves
  

• A Node diagnostic report at hang time: event loop idle (loopIdleTimeSeconds climbing), the only referenced active handle is one idle Postgres TCP socket (readable, no data pending), no timers. On the Postgres side that connection is state=idle, wait_event=ClientRead (server already answered, waiting for the client) — i.e. the client is awaiting a completion that will never come.

What was ruled out (all still hang on ARM64)

base image node:20-slim / node:22-slim / node:20 / node:20-alpine; seccomp=unconfined; UV_USE_IO_URING=0; Docker embedded DNS (tested via direct IP); Redis on/off; MTU; telemetry; --skip-links / --skip-scripts / --concurrency 1; Medusa 2.16.0 and 2.17.2.

Impact

Medusa cannot run its own migrations on ARM64 Linux hosts (e.g. Oracle Ampere, AWS Graviton) — a common/cheap deployment target. Runtime (medusa start) works fine on ARM64; only the migrator deadlocks. Current workaround: run medusa db:migrate from an x86_64 machine against the same DB.

Happy to provide the full async_hooks dump / diagnostic report.

[medusa-os-bot]

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

medusa db:migrate hangs forever on aarch64/ARM64 Linux but completes on x86_64 with the same project/DB. Reproducible from a fresh create-medusa-app across Medusa 2.16/2.17 and Node 20/22. Reporter traces it to an unresolved promise in modules-sdk runMigrations -> knex.transactio

[shahednasser]

Thank you for opening this issue @aigoup . After investigating, this is likely due to connecting to the database either on non-localhost or Docker service name. Can you clarify that if you disable ssl in your medusa-config.ts that fixes the issue?

module.exports = defineConfig({
  projectConfig: {
    databaseUrl: process.env.DATABASE_URL,
    databaseDriverOptions: {
      connection: {
        ssl: false,
      },
    },
    // ...
  },
})

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

[aigoup]

Hi, shahednasser

Thank you for following up on my issue, and for the new troubleshooting guide and PR #16100 — the better error messages will definitely help others.

I tested your suggestion today on the affected machine, using exactly the config you provided:

module.exports = defineConfig({
  projectConfig: {
    databaseUrl: process.env.DATABASE_URL,
    databaseDriverOptions: {
      connection: {
        ssl: false,
      },
    },
  },
})
Unfortunately, disabling ssl does not fix the issue — the behavior is completely unchanged. Here are the two test runs, side by side.

Environment (same as in my original report):

Oracle Cloud Ampere A1, aarch64, Ubuntu 24.04 (kernel 6.8)
Node v20.20.2 (official node:20 Debian image), Medusa 2.17.2
Postgres 16 via Docker Compose; DATABASE_URL=postgres://…@postgres:5432/ — so yes, a Docker service name (non-localhost), as you suspected
Test A — current config (no databaseDriverOptions):
npx medusa db:migrate boots fully — all modules load and the link checks run queries against the database successfully — then prints Running migrations... and hangs indefinitely (I killed it with timeout 120):

{"level":"info","message":"No link to load from /app/node_modules/@medusajs/draft-order/.medusa/server/src/links. skipped."}
{"level":"info","message":"Running migrations..."}   ← hangs here forever
EXIT=124 (timeout)
Test B — with databaseDriverOptions: { connection: { ssl: false } }:
Identical result — boots, prints Running migrations..., hangs, EXIT=124.

Why I don't believe this is a connection/SSL problem:

The hang occurs after the connection is established — by the time Running migrations... is printed, the CLI has already connected to Postgres and executed queries against it (module and link loading all succeed).
The production server runs in the same container with the same DATABASE_URL (Docker service name, no ssl options) and serves traffic 24/7 with zero connection issues.
The exact same code against the exact same database migrates successfully when medusa db:migrate is run from an x86_64 machine (GitHub Actions ubuntu-latest, and also macOS) through an SSH tunnel to this Postgres instance. That is our production workaround today: an x86 CI job runs the migrations, then the ARM box deploys.
Plain knex queries and the full Medusa runtime both work fine on this ARM box — only the migrator hangs.
So the variable that flips the result is the CPU architecture (aarch64 vs x86_64), not the connection target or SSL. When I originally traced it, the deadlock appeared to be inside the modules-sdk migration path, with async-hooks involved — details are in my original report.

The hang is 100% reproducible on this machine, so I'm happy to run any diagnostic build or patch here if that would help you narrow it down.

Best regards,
(GitHub: @aigoup)

[shahednasser]

Thank you for all the details @aigoup . Can you test out your project with version 2.18.0-snapshot-20260720081049 of all medusa packages (except @medusajs/ui)? Or run create-medusa-app app --version 2.18.0-snapshot-20260720081049 --skip-db --no-browser for testing in a new project.

This version doesn't fix the issue, as it's not clear what it is, but instead of hanging the migration fail should fail with the actual error.

[aigoup]

Thanks @shahednasser — the snapshot did exactly what you described: instead of hanging, db:migrate now fails with an error after ~10s. And the output is revealing. Env: aarch64, Ubuntu 24.04 (kernel 6.8), Node v20.20.2, Postgres 16 (Docker). All @medusajs/* on 2.18.0-snapshot-20260720081049 except @medusajs/ui. I ran it against a fresh empty database over the Docker service name (postgres:5432) — the exact setup from the report. npx medusa db:migrate output: *info: Running migrations...info: Creating migrations table 'mikro_orm_migrations'...info: Migrations table created successfullyerror: Could not connect to the database while running migrations. The connection timed out after 10 seconds, which usually indicates an incorrect database URL or an SSL configuration issue.MedusaError: Could not connect to the database while running migrations. The connectiontimed out after 10 seconds ... at Timeout.<anonymous> ***@***.***/modules-sdk/src/medusa-app.ts:72:9) at listOnTimeout (node:internal/timers:581:17) at processTimers (node:internal/timers:519:7) { __isMedusaError: true, type: 'database_error', code: undefined,}* The key finding — it is NOT the URL or SSL (despite what the message guesses): Immediately before the timeout, the migrator successfully connected and created the mikro_orm_migrations table using that same DATABASE_URL. I confirmed the table exists in the DB afterward. So the connection/URL/SSL are fine — the first phase works. The timeout then fires in @medusajs/modules-sdk/src/medusa-app.ts:72, i.e. when the modules-sdk sets up its own connection(s) to run the per-module migrations. On 2.17.2 this same step hangs forever; the snapshot's 10s cap just turns that hang into this error. This lines up with the original trace: the deadlock is in the modules-sdk migration path, and it's architecture-specific — the identical code + same database migrates fine when db:migrate runs on x86_64 (our production workaround runs migrations from an x86 CI runner over a tunnel, then the ARM box deploys). So the misleading part is that the error attributes it to URL/SSL, when the real problem is that the modules-sdk migration connection step can't establish (or times out) on aarch64 after the initial connection already succeeded. Minor note: with @medusajs/ui pinned (as you suggested), npm install ERESOLVE'd because the snapshot @medusajs/draft-order peer-wants @***@***.***; I used --legacy-peer-deps to proceed (ui isn't involved in migrations). Happy to run any patch or add diagnostic logging around medusa-app.ts:72 — I can reproduce this 100% on this ARM box in an isolated throwaway DB.

…

On Mon, Jul 20, 2026 at 4:38 PM Shahed Nasser ***@***.***> wrote: *shahednasser* left a comment (medusajs/medusa#16011) <#16011 (comment)> Thank you for all the details @aigoup <https://github.com/aigoup> . Can you test out your project with version 2.18.0-snapshot-20260720081049 of all medusa packages (except @medusajs/ui)? Or run create-medusa-app app --version 2.18.0-snapshot-20260720081049 --skip-db --no-browser for testing in a new project. This version doesn't fix the issue, as it's not clear what it is, but instead of hanging the migration fail should fail with the actual error. — Reply to this email directly, view it on GitHub <#16011?email_source=notifications&email_token=BQ6BG64X4XWUBCJ6K6GXI5T5FXLBFA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKMBSGAZTAMZXGY3KM4TFMFZW63VHNVSW45DJN5XKKZLWMVXHJLDGN5XXIZLSL5RWY2LDNM#issuecomment-5020303766>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BQ6BG63CB277IZFYZ54D7F35FXLBFAVCNFSNUABFKJSXA33TNF2G64TZHMZDGNBXGM4TSNZWHNEXG43VMU5TIOBWGQ3DGNBVGM42C5QC> . Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS <https://github.com/notifications/mobile/ios/BQ6BG64XVM5PP6JPMR6LEKT5FXLBFA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKMBSGAZTAMZXGY3KM4TFMFZW63VHNVSW45DJN5XKKZLWMVXHJKTGN5XXIZLSL5UW64Y> and Android <https://github.com/notifications/mobile/android/BQ6BG65GBIT4D6ZEZQA5HI35FXLBFA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKMBSGAZTAMZXGY3KM4TFMFZW63VHNVSW45DJN5XKKZLWMVXHJLTGN5XXIZLSL5QW4ZDSN5UWI>. Download it today! You are receiving this because you were mentioned.Message ID: ***@***.***>