Diagnosing Nuxt.js Middleware Misconfiguration: A Step‑by‑Step Guide

Recognizing the Symptoms

When a Nuxt application behaves unexpectedly, the first clues often point to middleware problems:

• Pages fail to render data or show empty placeholders.
• Unexpected redirects or 404s appear after a navigation.
• Server‑side errors such as Cannot find module or export default is not a function surface in the console.
• Console logs show “Unhandled Promise Rejection” or “ReferenceError: window is not defined” during SSR.

These symptoms usually result from a mis‑named file, wrong export, incorrect path reference, or execution‑context mismatch.

Common Causes & Quick Reference

Condition	Likely Cause	Quick Check
File not found	Wrong folder or filename	ls -R src/middleware
Export error	Missing default export or wrong signature	grep -R "export default" src/middleware
Wrong path in nuxt.config	Incorrect relative path or typo	cat nuxt.config.js | grep middleware
Execution context crash	Browser API used in SSR	Search for window/document in middleware
Order conflict	Global middleware runs before route middleware	Check middleware array order in nuxt.config

Ordered Diagnostic Checklist

1. Verify File Location and Naming

   Nuxt expects middleware files in ./middleware (or ./server/middleware for server‑only). Filenames are case‑sensitive.

   # On Linux/macOS
   ls -R src/middleware
   

2. Confirm Export

   Middleware must export a default async or sync function. A common mistake is exporting a named function or missing default.

   // src/middleware/auth.js
   export default async (context) => {
     // ...
   }
   

3. Check nuxt.config Path References

   Paths in router.middleware or serverMiddleware are relative to the project root.

   // nuxt.config.js
   export default {
     router: {
       middleware: ['auth'] // resolves to src/middleware/auth.js
     }
   }
   

4. Inspect Execution Context

   Middleware runs on both server and client. Guard browser‑only code with process.client or typeof window !== 'undefined'.

   if (process.client) {
     // safe to use window
   }
   

5. Verify Order and Conflicts

   Global middleware defined in router.middleware runs before route‑specific middleware. Misordered redirects can cause loops.

   // nuxt.config.js
   router: {
     middleware: ['global', 'auth']
   }
   

Fixes Tied to Findings

• File not found – Move the file to ./middleware or correct the path in nuxt.config.
• Export error – Ensure export default is present and the function signature matches (context) or (req, res, next) for serverMiddleware.
• Wrong path – Use absolute paths or double‑check the folder name; remember case sensitivity.
• SSR crash – Wrap browser APIs with process.client or move the code to clientMiddleware.
• Order conflict – Re‑order the array or split logic into separate middleware files with clear naming.

Concrete Example: Auth Middleware

Below is a minimal auth middleware that redirects unauthenticated users to /login. It demonstrates correct export, path reference, and client guard.

// src/middleware/auth.js
export default async (context) => {
  const { req, redirect, store } = context
  // During SSR, read cookie; on client, use store state
  const isAuthenticated = process.server ?
    req.headers.cookie?.includes('token=') :
    store.state.auth.token

  if (!isAuthenticated) {
    return redirect('/login')
  }
}

Configure it globally in nuxt.config.js:

export default {
  router: {
    middleware: ['auth']
  }
}

Verification Steps

1. Add a console.log inside the middleware to confirm execution:

   console.log('Auth middleware executed', { route: context.route.path })
   

2. Run the dev server with debug output to see middleware bundling:

   npx nuxt dev --debug
   

3. Navigate to a protected route and verify the redirect occurs. Inspect the browser console for the log message.
4. Check Node logs for SSR execution and ensure no window is not defined errors appear.

Escalation Criteria

• If the middleware still crashes after applying the fixes, open a new issue in the Nuxt repository with the error stack, Nuxt version, and nuxt.config snippet.
• When middleware performance degrades page load times, profile the function with console.time or a dedicated profiler.
• If you suspect a bug in Nuxt’s middleware handling, reproduce the issue in a minimal repo and submit a pull request.