Next.js middleware (proxy) does not run for my routes
console.log inside middleware never printsShort 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.
Fix it fast
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/dashboard2Match what you see, then jump to its fix
What does the error look like?
console.log inside middleware never printsRedirects and rewrites from middleware do nothingMiddleware 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/null2Fix
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
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/null2Fix
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.icoConfirmed by nextjs.org
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/dashboardConfirmed by nextjs.org
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
Web apps
Upgrading to Next.js 16: middleware becomes proxy, and the other things that break
Missing Required default.js for Parallel Route
Next.js 16 renames middleware.ts to proxy.ts and its exported function to proxy.
6 causes, each with a fixWeb apps
Apollo Server rejects a request as a potential CSRF
HTTP 400 Bad Request from the GraphQL endpoint
Apollo Server's CSRF prevention is on by default.
3 causes, each with a fixWeb apps
Clerk cannot read its publishable key in a Next.js app
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY is undefined
Clerk reads NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY.
3 causes, each with a fixWeb apps
The shell cannot find create-next-app
command not found: create-next-app
create-next-app is not meant to be installed as a shell command.
2 causes, each with a fixWeb apps
ESLint fails with: Cannot find module 'next/babel'
ESLint stops on the first file with a Babel or parser error instead of listing lint results
next/babel is a Babel preset that ships inside the next package.
3 causes, each with a fixWeb apps
Firebase Auth says the API key is not valid
Firebase: Error (auth/api-key-not-valid.-please-pass-a-valid-api-key.)
The apiKey your app sends is either empty, wrong, or blocked.
4 causes, each with a fix