Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

Next.js middleware (proxy) does not run for my routes

Errorconsole.log inside middleware never prints

Short answer

Next.js runs middleware only when the file sits at the project root (or in src) beside app or pages, exports a function with the right name, and the matcher covers the request path. Since Next.js 16 the file is called proxy.ts with a function named proxy. A static export never runs it.

  • Applies to Next.js 15, Next.js 16, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Put one log line at the top of the function and request the path with curl. If nothing appears in the terminal where next dev runs, the file is not being picked up (causes 1 and 3). If it appears for other paths but not yours, look at the matcher (cause 2).

    # first line of the exported function
    console.log('proxy hit', request.nextUrl.pathname)
    
    curl -I http://localhost:3000/dashboard
  2. 2Match what you see, then jump to its fix

    1. 1No log at all, for any path.The file has the wrong place, name or exportFix
    2. 2The log appears for some paths, not the one you expect.The matcher does not cover the requestFix
    3. 3Works in next dev, never runs in production, and next.config has output: 'export'.The app is a static exportFix

What does the error look like?

  • console.log inside middleware never prints
  • Redirects and rewrites from middleware do nothing
  • Middleware runs for pages but not for /api or static paths

Cause 1 of 3

The file has the wrong place, name or export

1Check

The file must be in the project root, or in src when you use one, at the same level as app or pages. It exports either a default function or one named proxy. In Next.js 15 and earlier the file and function are called middleware. If pageExtensions is customised, the file name needs the same extension.

ls middleware.* proxy.* src/middleware.* src/proxy.* 2>/dev/null
grep -n "pageExtensions" next.config.*
grep -nE "export (default )?(async )?function (proxy|middleware)" proxy.* middleware.* src/proxy.* src/middleware.* 2>/dev/null

2Fix

Move the file next to app or pages and name it for your version. Only one proxy file per project is supported. To migrate from the old name, run the official codemod.

# Next.js 16
mv middleware.ts proxy.ts      # and rename the function to proxy
# or let the codemod do both
npx @next/codemod@canary middleware-to-proxy .

3Verify

Restart the dev server and request any page. The log line appears.

curl -I http://localhost:3000/

Confirmed by nextjs.org

Did this fix it?

Cause 2 of 3

The matcher does not cover the request

1Check

A matcher entry must start with /, is anchored to the start of the path (/about matches /about and /about/team but not /blog/about), and a named parameter such as /about/:path matches only one more segment. Values must be constants; a variable in the matcher is ignored.

grep -n -A8 "matcher" proxy.ts middleware.ts src/proxy.ts src/middleware.ts 2>/dev/null

2Fix

Widen the pattern, using :path* for any depth. Without a matcher the function runs on every request, including static files, so a broad rule normally excludes them.

export const config = {
  matcher: [
    '/((?!api|_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)',
  ],
}

3Verify

Request one path that should match and one that should not, and compare the logs.

curl -I http://localhost:3000/dashboard/settings
curl -I http://localhost:3000/favicon.ico

Confirmed by nextjs.org

Did this fix it?

Cause 3 of 3

The app is a static export

1Check

A static export produces plain files with no server in front of them, so there is nothing to run the function. The proxy docs list static export as unsupported.

grep -n "output" next.config.*

2Fix

Deploy to a Node.js server, a Docker container or a platform adapter instead of a static export, or move the logic to the web server or CDN that serves the files.

// next.config.ts: remove this line to allow a server
// output: 'export',

3Verify

Build, start the server and request a path the function should redirect.

npx next build && npx next start
curl -I http://localhost:3000/dashboard

Confirmed by nextjs.org

Did this fix it?

How do I stop it coming back?

  • Keep one proxy or middleware file at the project root and log the path while you write the matcher.
  • Use a negative matcher so the function skips _next/static, _next/image and public files.
  • Do not rely on the function alone for authorisation; check access again in the page, route handler or Server Function.
  • Test the matcher with the unstable_doesMiddlewareMatch helper from next/experimental/testing/server.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.