[Bug]: route/middleware with matcher "/" (bare root) silently never registers

[efragosogit]

System information

package.json (relevant deps)

{
  "dependencies": {
    "@medusajs/admin-sdk": "2.17.2",
    "@medusajs/cli": "2.17.2",
    "@medusajs/admin-shared": "2.17.2",
    "@medusajs/cache-redis": "2.17.2",
    "@medusajs/dashboard": "2.17.2",
    "@medusajs/event-bus-redis": "2.17.2",
    "@medusajs/framework": "2.17.2",
    "@medusajs/js-sdk": "2.17.2",
    "@medusajs/medusa": "2.17.2",
    "@medusajs/ui": "4.1.19"
  }
}

• Node.js version: v24.15.0
• Database: PostgreSQL (Railway-hosted, version not relevant to this bug — it's pure HTTP routing)
• OS: macOS 26.0.1 (reproduced via medusa develop; the workaround described below was separately verified working on a Railway/Linux production deployment, so the underlying issue is not OS-specific, though I didn't re-verify the unpatched 404 behavior on Linux specifically)
• Browser: N/A (server-side routing bug, reproducible via curl)

What happened?

A custom API route file at src/api/route.ts (which should map to the bare root path / under Medusa's file-based routing convention), or a global middleware registered via defineMiddlewares with matcher: "/", is silently never registered with Express. No error is thrown at build time or at server startup — the request to / simply returns a plain 404, identical to a path with no matching route at all.

The same file-based routing convention works correctly for any path with at least one segment (e.g. src/api/ping/route.ts → /ping registers and responds correctly).

Root cause

Traced it to packages/core/framework → src/http/routes-sorter.ts (compiled: dist/http/routes-sorter.js), in the private method that builds the routing tree used before routes are registered on the Express app:

_RoutesSorter_processRoute = function _RoutesSorter_processRoute(route) {
    const segments = route.matcher.split("/").filter((s) => s.length);
    let parent = this.__routesTree["root"];
    segments.forEach((segment, index) => {
        // ... bucket classification (static/wildcard/regex/params/global) ...
        if (index + 1 === segments.length) {
            parent[bucket].routes.push(route);
            return;
        }
        // ... descend into children ...
    });
};

For a route/middleware with matcher: "/":

"/".split("/")          // => ["", ""]
  .filter(s => s.length) // => []  (both segments are empty strings, filtered out)

segments ends up as an empty array. Since the loop that actually does parent[bucket].routes.push(route) only runs inside segments.forEach(...), and there are zero segments to iterate, the route is never pushed into any bucket of the tree — it silently disappears before RoutesSorter.sort() ever returns it, and therefore it's never passed to app.get() / app.use() in the ApiLoader.

This affects both mechanisms:

1. A route.ts file placed directly at the root of src/api/ (no subfolder).
2. A middleware registered via defineMiddlewares({ routes: [{ matcher: "/", middlewares: [...] }] }).

Reproduction

Minimal repro (tested locally with medusa develop, on a project based on the official medusajs/b2b-starter template):

// src/api/route.ts
import { MedusaRequest, MedusaResponse } from "@medusajs/framework";

export const GET = async (req: MedusaRequest, res: MedusaResponse) => {
  res.json({ ok: true });
};

medusa develop
curl -i http://localhost:9000/
# HTTP/1.1 404 Not Found   <-- expected: {"ok":true}

For comparison, the identical file one level deeper works fine:

// src/api/ping/route.ts  (same handler body)

curl -i http://localhost:9000/ping
# HTTP/1.1 200 OK   {"ok":true}

Same silent no-op happens with a middleware-only approach (no route file at all):

// src/api/middlewares.ts
import { defineMiddlewares } from "@medusajs/medusa";

export default defineMiddlewares({
  routes: [
    {
      matcher: "/",
      middlewares: [(req, res, next) => { res.redirect("/app"); }],
    },
  ],
});

GET / still 404s — the middleware handler is never invoked (confirmed with a console.log inside it that never printed).

Expected behavior

A route file at src/api/route.ts, or a defineMiddlewares entry with matcher: "/", should register and handle requests to the bare root path /, the same way any other file-based route or middleware matcher does.

Actual behavior

The route/middleware is silently dropped during the routes-sorting step (see root cause above) and is never registered on the Express app. Requests to / always fall through to Medusa's default 404 handler, with no warning or error logged anywhere (dev or production).

Suggested fix

In _RoutesSorter_processRoute, special-case the zero-segment (bare root) matcher before the forEach, e.g.:

if (segments.length === 0) {
    const bucket = (!route.methods && !route.method) ? "global" : "static";
    this.__routesTree["root"][bucket].routes.push(route);
    return;
}

Workaround (for anyone hitting this in the meantime)

Register a middleware with matcher: "*" instead (which does produce one segment and registers correctly), and guard inside the handler using req.originalUrl === "/" (not req.path, which gets rewritten relative to the "*" mount point and is always "/" for every request once inside that middleware — an easy way to accidentally redirect every route on your API if you check the wrong property):

{
  matcher: "*",
  middlewares: [
    (req, res, next) => {
      if (req.originalUrl === "/") {
        return res.redirect("/app/login");
      }
      next();
    },
  ],
}

Link to reproduction repo

I don't have a minimal public repro repo handy, but the reproduction above is 4 lines of code and reproduces on a completely vanilla create-medusa-app scaffold — happy to put one together if it'd help triage.

[medusa-os-bot]

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

Confirmed bug in v2.17.2: routes and middlewares with a bare root matcher '/' are silently dropped by RoutesSorter._processRoute. The split/filter step on '/' yields an empty segments array, so the forEach never executes and the route is never pushed into any bucket — it never reaches Express. A zero-segments guard that pushes directly to the root branch is already present in the develop branch (packages/core/framework/src/http/routes-sorter.ts). The fix will be included in a future release. Reporter provides a workaround using matcher '*' with req.originalUrl check.

[sham-jadhav03]

Hi team! Is this issue already fixed on the develop branch?

I noticed the bot mentioned that a zero-segments guard was added to packages/core/framework/src/http/routes-sorter.ts. Could you confirm if this issue is already solved or if it's still open for a community PR? I’d be happy to submit a PR if it's still open!

[apoorva-01]

Confirmed still broken on develop, and the bot's note about a zero-segments guard being present isn't right. There's no such guard there today.

The loader itself generates the "/" matcher for a root route.ts. createRoutePath does /${segments.filter(Boolean).map(...).join("/")}, which for a root file is /${[].join("/")} = "/". Then RoutesSorter drops it:

// #processRoute
const segments = route.matcher.split("/").filter((s) => s.length)
segments.forEach(...)  // matcher "/" -> segments = [], loop never runs

So the loader produces a "/" matcher and the sorter silently throws it away before it reaches Express. Hence the 404.

The fix is a small special-case in #processRoute: when segments is empty, push the route straight into the root branch's bucket (global for methodless middleware, static otherwise) instead of leaning on the forEach. Happy to send a PR with a test in routes-sorter.spec.ts if that's the direction you want, or leave it to @sham-jadhav03 if they've already started.

Does that approach look right?

[KallinikosMil]

This looks like it's already fixed on develop. The empty-segments case is handled in RoutesSorter#processRoute now:

const segments = route.matcher.split("/").filter((s) => s.length)

// A matcher without any segments (e.g. "/") targets the root. Placing it
// directly on the root branch ensures it is not dropped from the tree.
if (!segments.length) {
  const bucket = !route.methods && !route.method ? "global" : "static"
  parent[bucket].routes.push(route)
  return
}

That guard came in with d76952b (#16066, "fix(framework): fix middlewares regex matcher") on 2026-07-15, which also added the RegExp branch just above it. git tag --contains d76952b5b0 gives v2.18.0 (released 2026-07-23).

The report is against 2.17.2 (2026-07-01), which predates the fix — so upgrading to >= 2.18.0 should make both src/api/route.ts and matcher: "/" register. Worth a quick confirmation from the reporter before closing.

[sham-jadhav03]

Thanks for pointing this out, @KallinikosMil. Glad to know it was already addressed in v2.18.0. I'll close/withdraw my PR accordingly.