Invalid default export found in ${absolutePath}. Make sure t

Error message

Invalid default export found in ${absolutePath}. Make sure to use "defineMiddlewares" function and export its output.

What it means

Emitted while Medusa loads middleware files from src/api/middlewares (or a plugin's api/middlewares directory). processMiddlewareFile expects the file's default export to be the result of defineMiddlewares() with a routes array; if routes is missing or not an array, the file is silently skipped with this warning. It is a warning, not a throw, so the rest of the app boots without the middleware.

Source

Thrown at packages/core/framework/src/http/middleware-file-loader.ts:68

   */
  async #processMiddlewareFile(absolutePath: string): Promise<void> {
    const middlewareExports = await dynamicImport(absolutePath)

    if (isFileSkipped(middlewareExports)) {
      return
    }

    const middlewareConfig = middlewareExports.default
    if (!middlewareConfig) {
      logger.warn(
        `No middleware configuration found in ${absolutePath}. Skipping middleware configuration.`
      )
      return
    }

    const routes = middlewareConfig.routes as MiddlewaresConfig["routes"]
    if (!routes || !Array.isArray(routes)) {
      logger.warn(
        `Invalid default export found in ${absolutePath}. Make sure to use "defineMiddlewares" function and export its output.`
      )
      return
    }

    const result = routes.reduce<{
      bodyParserConfigRoutes: BodyParserConfigRoute[]
      additionalDataValidatorRoutes: AdditionalDataValidatorRoute[]
      middleware: MiddlewareDescriptor[]
    }>(
      (result, route) => {
        if (!route.matcher) {
          throw new Error(
            `Middleware is missing a \`matcher\` field. The 'matcher' field is required when applying middleware. ${JSON.stringify(
              route,
              null,
              2
            )}`

View on GitHub (pinned to 5e06e544a2)

Solutions

Open the file named in ${absolutePath} and wrap the config: export default defineMiddlewares({ routes: [...] })
Verify the key is exactly `routes` and is an array of route entries (method, matcher, middlewares)
Delete the file if it is an accidental/experimental file left in src/api/middlewares
Restart medusa dev — middleware files are only scanned at startup/reload

Example fix

// before
export default {
  route: [
    { method: "GET", matcher: "/admin/products", middlewares: [myMid] },
  ],
}

// after
import { defineMiddlewares } from "@medusajs/framework/http"
export default defineMiddlewares({
  routes: [
    { method: "GET", matcher: "/admin/products", middlewares: [myMid] },
  ],
})

Defensive patterns

Strategy: validation

Validate before calling

// before export
const config = defineMiddlewares({ routes: [/* ... */] })
if (!config || !Array.isArray(config.routes)) {
  throw new Error("Invalid middleware config")
}
export default config

Type guard

const isMiddlewaresConfig = (v: unknown): v is { routes: unknown[] } =>
  typeof v === "object" && v !== null && Array.isArray((v as any).routes)

Prevention

Always export default defineMiddlewares({ routes: [...] }) from files in src/api/middlewares
Type the export explicitly so TS rejects bad shapes
Keep only middleware files in the middlewares directory

When it happens

Trigger: A file in src/api/middlewares/*.ts whose default export is not wrapped in defineMiddlewares(), or whose object literal has no `routes` key (e.g. exporting { routes: undefined }, a plain function, or an object with only `errorHandler`).

Common situations: Copying middleware snippets from older Medusa v1 docs/tutorials that exported a plain config object, typos like `route:` instead of `routes:`, or forgetting the `export default` on the defineMiddlewares() call.

Related errors

AI-assisted analysis of medusajs/medusa@5e06e544a2 (2026-08-27). Data as JSON: /api/errors/d0b656b58d67a2e8. Report an issue: GitHub.