Next.js Middleware Error: middleware.ts failed to compile or execute

What causes this error

Next.js middleware runs in the Edge Runtime — a lightweight V8-based environment that supports Web APIs but not the full Node.js runtime. When middleware.ts imports a Node.js-specific module (fs, path, net, child_process, or node: prefixed imports), the Edge Runtime compiler rejects it at build time. At runtime, common failures include infinite redirect loops (middleware redirects to a path that matches its own matcher), incorrect matcher patterns (the route never triggers or triggers on every request including _next/static), and errors from accessing request properties incorrectly. The middleware file must also be placed in the correct location — the project root alongside the app or pages directory, not inside app/.

How to fix it

1. 01

   step 1

   Fix Node.js import errors in Edge Runtime

   The Edge Runtime does not support Node.js built-in modules. If your middleware imports a library that depends on fs, path, crypto (the full Node.js version), or any other built-in, the build fails. Replace with Edge-compatible alternatives or use the Web Crypto API.

   // BAD: Node.js crypto — fails in Edge Runtime
   // import crypto from 'crypto';
   // const hash = crypto.createHash('sha256').update(token).digest('hex');
   
   // GOOD: Web Crypto API — works in Edge Runtime
   const encoder = new TextEncoder();
   const data = encoder.encode(token);
   const hashBuffer = await crypto.subtle.digest('SHA-256', data);
   const hashArray = Array.from(new Uint8Array(hashBuffer));
   const hash = hashArray.map(b => b.toString(16).padStart(2, '0')).join('');

   Copy
2. 02

   step 2

   Fix the middleware file location

   middleware.ts must be in the project root — the same level as your app/ or pages/ directory. If it is inside app/middleware.ts or src/app/middleware.ts, Next.js will not recognize it. For projects using the src/ directory, place it at src/middleware.ts.

   # Correct locations:
   # project-root/middleware.ts     (no src/ directory)
   # project-root/src/middleware.ts (with src/ directory)
   
   # WRONG locations (will be silently ignored):
   # project-root/app/middleware.ts
   # project-root/pages/middleware.ts

   Copy
3. 03

   step 3

   Fix the matcher configuration

   The matcher determines which routes trigger the middleware. Common mistakes: missing the leading slash, using regex syntax instead of Next.js path patterns, or forgetting to exclude static assets. An overly broad matcher that catches _next/static or favicon.ico causes asset loading failures.

   export const config = {
     matcher: [
       // Match all routes except static files, images, and favicon
       '/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)',
     ],
   };
   
   // Or explicitly list protected routes:
   export const config = {
     matcher: ['/dashboard/:path*', '/api/protected/:path*'],
   };

   Copy
4. 04

   step 4

   Fix infinite redirect loops

   If middleware redirects to /login and /login also matches the middleware matcher, the browser hits a redirect loop (ERR_TOO_MANY_REDIRECTS). Either exclude the redirect target from the matcher, or add a condition to skip middleware on the login page.

   import { NextResponse } from 'next/server';
   import type { NextRequest } from 'next/server';
   
   export function middleware(request: NextRequest) {
     const { pathname } = request.nextUrl;
   
     // Skip middleware for login page to avoid redirect loop
     if (pathname === '/login') {
       return NextResponse.next();
     }
   
     const session = request.cookies.get('session');
     if (!session) {
       return NextResponse.redirect(new URL('/login', request.url));
     }
   
     return NextResponse.next();
   }
   
   export const config = {
     matcher: ['/dashboard/:path*', '/settings/:path*'],
   };

   Copy
5. 05

   step 5

   Debug middleware execution

   Middleware errors can be hard to trace because they run before the route handler. Use console.log in development — middleware logs appear in the terminal (not the browser console). In production, check your hosting provider's function logs.

   export function middleware(request: NextRequest) {
     console.log('Middleware hit:', request.nextUrl.pathname);
     console.log('Cookies:', request.cookies.getAll());
     console.log('Headers:', Object.fromEntries(request.headers));
   
     // Your middleware logic here
     return NextResponse.next();
   }

   Copy

How to verify the fix

• npm run build completes without middleware compilation errors.
• Protected routes redirect to login when no session cookie is present.
• The login page loads without an infinite redirect loop.
• Static assets (_next/static, images, favicon) load correctly and are not intercepted by middleware.