Common Next.js Errors and How to Fix Them

Next.js App Router components are server components by default. If you use useState, useEffect, onClick, or any browser API, you need 'use client' at the top of the file. If you use database queries or access server-only secrets, the component must stay as a server component. AI tools frequently mix these up — putting 'use client' on components that could be server components (wasting performance) or forgetting it on components that need it (causing build errors).

Next.js pre-renders pages at build time by default. If your component accesses window, document, or other browser-only APIs during render, the build will fail. Fix: wrap browser-only code in useEffect, or use next/dynamic with { ssr: false } for components that can only run in the browser.

In App Router, API routes are in app/api/[route]/route.ts and export named functions (GET, POST, etc.). Common mistakes: exporting default instead of named functions, forgetting to return a Response object, not handling all HTTP methods, and not validating request bodies.

Next.js middleware runs on every request by default — including static assets, images, and API routes. Always use the matcher config to restrict middleware to the routes that need it. Middleware runs in the Edge Runtime, which means you can't use Node.js-specific APIs like fs or most npm packages.

NEXT_PUBLIC_ variables are inlined at build time — changing them requires a rebuild. Server-only variables are available at runtime. If an environment variable is undefined, check: is it set in your hosting platform? Does it have the right prefix? Did you restart the dev server after adding it to .env.local?