Medusa.js 2.22.5 was superseded: how to upgrade safely to 2.22.6

You ran a routine patch upgrade to Medusa.js 2.22.5 because it carried a security fix. Now a plugin fails to resolve at boot, or CI went red on a module that was fine yesterday, or nothing broke and you are not sure whether that is luck. All three are plausible, because 2.22.5 went out with package files missing. Version 2.22.6 is the corrected release, and it is the one you should be on.

2.22.5 shipped incomplete and 2.22.6 replaces it

The 2.22.6 release notes are blunt: it supersedes v2.22.5, which was released with missing package files. The fix in 2.22.6 is described as including build output for the draft-order and loyalty plugin packages when packed with Yarn. In other words, the published tarballs for those packages did not contain their compiled code.

The security content has not changed. The 2.22.6 notes say that 2.22.5 included a security hardening fix and point to the 2.22.5 notes for the details and for patches to older versions. The 2.22.6 notes do not describe the fix themselves and give no severity or advisory identifier, so read the 2.22.5 notes directly before deciding how urgent this is for you. We will not restate it second-hand here.

The practical upshot:

• If you are on 2.22.4 or earlier, skip 2.22.5 and go straight to 2.22.6.
• If you are on 2.22.5, move to 2.22.6 even if everything appears to work.
• If you are pinned to an older minor and cannot move, the 2.22.5 notes are where the backported patches are listed.

A working 2.22.5 install is not proof you are fine

The named packages are draft-order and the loyalty plugin. If your project does not load either one, a 2.22.5 install may boot and serve traffic normally. That is the dangerous case, because it stays in the lockfile until someone enables draft orders or adds the plugin, and then the failure looks unrelated to an upgrade done weeks earlier.

The release notes describe 2.22.5 broadly as released with missing package files and name two packages in the fix. We would not assume the list is exhaustive from the outside. Treat any 2.22.5 entry in a lockfile as suspect and replace it.

Check the lockfile, not package.json

A caret range in package.json tells you nothing about what was installed. The lockfile does.

# Yarn
grep -n "2.22.5" yarn.lock
yarn why @medusajs/medusa

# npm
npm ls --all | grep "@medusajs/"

# pnpm
pnpm why -r "@medusajs/*"

You are looking for two things: any @medusajs/* package resolved to 2.22.5, and any mix of versions across the @medusajs/* scope. A mixed set is common after a partial upgrade, where the core packages moved and a plugin or the admin SDK did not.

Then look at what is on disk. Open the installed directory for the draft-order and loyalty packages under node_modules and check that there is compiled output, not just a package.json and a readme. If the entry point named in that package.json points at a file that does not exist, you have the broken build.

Check every place the lockfile gets resolved: local machines, CI caches, Docker layer caches, and any private registry mirror or proxy that may have cached the 2.22.5 tarballs.

Pin every @medusajs package to 2.22.6 and reinstall clean

Medusa.js packages are released together and expected to run together. For this upgrade we would drop the range operators and pin exact versions, then loosen them later if that is your policy.

1. Set every @medusajs/* dependency in package.json to 2.22.6, including dev dependencies, plugins from the same scope, and any package in a monorepo workspace that depends on them.
2. Delete node_modules and the lockfile entries for the scope. Regenerating the whole lockfile is the simplest way to be sure, as long as you review the resulting diff for unrelated bumps.
3. Clear the package manager cache, or at least confirm the install pulled fresh tarballs.
4. Install, then rerun the lockfile checks above. There should be zero matches for 2.22.5 and one version across the scope.
5. Rebuild Docker images without the cached dependency layer.
6. Run the build and any pending migrations in a staging environment before production.

Do not hand-edit the lockfile to swap version strings. The integrity hashes will not match and you will have a worse afternoon.

Smoke-test the APIs, and the orders list in particular

2.22.6 is not purely a repack. It carries two other fixes, and one of them changes a response shape.

The core-flows fix is described as: don't return order items in orders list unless requested. If any code of yours lists orders and reads items off each one without asking for them, it may now get nothing back for that field. Places to check:

• Storefront account pages that show order history with line items.
• Admin widgets or custom admin routes that summarise orders.
• Scheduled jobs, exports and integrations that page through orders and read items for fulfilment, accounting or an ERP sync.
• Custom workflows that call the order list flow and pass the result along.

The fix is to request items explicitly in the query. It is a small change, and the bug it prevents is a silent one: an export with empty line items does not throw.

The other fix restarts the dev server on Windows after a failed boot. It only matters for developers on Windows.

For the smoke test itself, cover at least: admin login, the product and order lists, opening a single order, creating a draft order if you use them, a storefront cart through to a completed test order, and every custom API route you own. For the custom routes, read the 2.22.5 security notes first, then test any route that passes request query parameters through to a query or filter. A hardening fix in that area is exactly where a route that leaned on permissive behaviour would start returning errors or different results.

What to do next

Today: grep the lockfile for 2.22.5. If it is there, schedule the move to 2.22.6 now, not at the next convenient sprint. If you are on an older line, read the 2.22.5 notes and apply the patch listed for your version.

This week: add a CI step that fails when @medusajs/* packages resolve to more than one version. It costs a few lines and catches the partial-upgrade problem before it reaches staging.

If you are partway through a move onto Medusa.js, do not let a bad patch release stall the cutover plan. Pin, verify, and keep going. Our approach to Magento 2 to Medusa.js or Vendure migrations treats dependency pinning and upgrade rehearsal as part of the migration, not an afterthought, and the broader migrations page covers the other source platforms. If you want a second set of eyes on an upgrade or a migration plan, get in touch.