Introduction

You ask AI to fix a fetch. It does. Types pass. The component renders. You push.

Then dev crawls to a stop. Or prod serves a blank page. Or GitHub says conflict on a file you never touched. The model did its job inside the file. It did not see the repo around it.

That gap is where most Next.js pain actually lives. Not broken JSX. Wrong root folder. Wrong env layer. Wrong deploy model. Stale git ref on the remote.

This list is the stuff that keeps surviving AI refactors, green CI, and clean local merges.

1. Next dev watching the whole monorepo

The problem

Your app sits inside a bigger repo. There is another lockfile above it. You run next dev, see a warning about multiple lockfiles, and keep going.

Compile gets slow. CPU stays high. Sometimes the machine feels stuck for no clear reason. AI will suggest faster imports or smaller components. It will not notice Next is indexing the wrong tree.

The fix

Pin Turbopack to the app folder in next.config.ts:


import path from "node:path";
import { fileURLToPath } from "node:url";

const appRoot = path.dirname(fileURLToPath(import.meta.url));

export default {
  turbopack: { root: appRoot },
};

Enter fullscreen mode Exit fullscreen mode

This applies to certain monorepo/workspace setups.
It is not the solution for every slow Next.js dev environment.

If that lockfile warning shows up, treat it as a bug, not noise.

2. Putting server secrets in `NEXT_PUBLIC_*`

The problem

AI puts API URLs and tokens in NEXT_PUBLIC_* because that is what client fetch examples use. Those values ship in the browser bundle. Anyone can read them in the built JS.

Or the opposite: server route handlers need an upstream URL that only exists as a public var pointing somewhere else. Local dev works with a hack. Prod does not.

The fix

Split by runtime:

Browser code → NEXT_PUBLIC_* only
Route handlers / server code → server env vars (no NEXT_PUBLIC_ prefix)

Upstream URLs and service tokens stay on the server. Client calls your BFF or the public API surface. Never both through one env var.

3. API address missing or duplicating `/api/v1`

The problem

One backend expects calls to https://api.example.com. Another expects https://api.example.com/api/v1. Your code adds paths on top of the base address. Get it wrong by one segment and every request 404s.

This often happens when you copy .env.local from another app in the same repo. AI copies the fetch code correctly. It does not check whether the base address matches this app.

The fix

Open that app's .env.example. See exactly how it builds URLs. Match that. Do not assume all apps in one company use the same address format.

4. Adding server API files to an app that deploys as static `HTML`

The problem

Some Next apps are built with output: "export". That means the output is plain HTML, CSS, and JS files uploaded to static hosting (like S3 or Amplify static). There is no Node server running your app in production.

You can add files under app/api/ and they may work in local dev. They will not exist after a static build. The hosting serves files, not your API routes.

AI often suggests "add an API route to hide the token" without checking how the app is deployed.

The fix

If you deploy as static files, the browser calls your backend directly and your backend must allow that origin (CORS).

If you need a server middle layer to hide tokens, you cannot deploy as a pure static export. You need hosting that runs Next.js server code.

Pick one. Mixing both without knowing it is a common break.

5. Local proxy setup that does not exist in production

The problem

In local dev, teams often add a proxy in next.config so calls to /api/v1/... get forwarded to a real server. Same website address, no cross-origin browser errors. Works great on your machine.

A static production build does not include that proxy. The browser still calls /api/v1/... on your static site address. Those requests never reach your backend.

AI adds the proxy config. It rarely asks how you deploy.

The fix

Use different setup for dev and prod:

Dev: proxy in next.config if you want
Prod: full backend URL in env, CORS enabled on the backend

Run next build the same way CI does before you call it done. next dev alone is not enough.

6. Server-only code imported in a client component

The problem

Next has a hard line between server code and client code. Files marked "use client" run in the browser. Things like reading request headers or secret env vars only work on the server.

One shared lib/api.ts file often gets imported everywhere. AI merges duplicate files and accidentally puts server code inside a client component. Build fails or you get strange runtime errors.

The fix

Keep two files:

One for the browser (simple fetch, public env only)
One for the server (secret env, used only in app/api routes or server components)

If it reads cookies, headers, or private env, it never goes in a "use client" file.

7. Login token is valid but for the wrong app

The problem

Some apps check two things: is the user logged in, and does their role match this specific product. You paste a login token into .env.local. It is not expired. The app still sends you back to the login page.

The token belongs to a different dashboard or role. AI tries to fix the redirect logic. The check is working. Your token is for the wrong app.

The fix

Make sure three things match: the role setting in env, the role inside the token, and what the app's auth guard expects. When testing locally, use a token created for this app specifically.

8. Fake login still turned on while shipping real auth

The problem

Many teams add a dev-only flag that skips real login so they can build UI faster. Useful. Easy to forget about.

You say auth is done. But callback, token refresh, sign out, and role redirect were never tested with real login. AI sees a user object in state and assumes auth works.

The fix

Use the skip-login flag only for UI work. Before merging: turn it off, log in for real, open a protected page, sign out.

9. Old dev server still running on the port

The problem

You run pnpm dev again without closing the last one. Port 3000 is busy. Next starts on 3001. You keep refreshing 3000 and see the wrong app or nothing useful.

AI will debug your React code. It will not check which process owns the port.

The fix


lsof -i :3000

Enter fullscreen mode Exit fullscreen mode

Kill the old process. Start fresh. Confirm which port the terminal says before debugging anything else.

10. No conflict on your machine, conflict on GitHub

The problem

You updated your branch with the latest main locally. Merge looks clean. The pull request on GitHub still shows conflicts.

Your local branch and the copy on GitHub are not the same history anymore. GitHub compares the remote branch to main, not your rebased local copy.

AI says "pull main again." You already did. On your machine only.

The fix

After rebasing locally, update GitHub:

git push --force-with-lease origin your-branch

Enter fullscreen mode Exit fullscreen mode

Only use this when you intentionally rebased or rewrote branch history.

Check they match:

git log origin/your-branch..HEAD

Enter fullscreen mode Exit fullscreen mode

No output means local and remote are in sync.

11. Expired login token in your env file

The problem

For local development, some apps read a login token from .env.local and attach it to server-side API calls. Tokens expire. Handlers return 401 Unauthorized. The UI shows empty data or error states.

Looks like the API is broken. AI rewrites error handling. The token is just old.

The fix

Decode the token and check the expiry time. Get a fresh one from a real login. Treat dev tokens like passwords with an expiration date.

12. Public env vars set after the build, not during it

The problem

NEXT_PUBLIC_ values are written into the JavaScript at build time.

If you set them in your hosting dashboard after the build already ran, the live site still has the old values baked in.

Works on your machine with .env.local. Wrong API address or app setting in production.

The fix

Make sure public env vars exist before next build runs in CI. Some teams write a .env.production file in the build step. Check build logs, not just runtime settings in the host UI.

13. Copied env from the wrong app in the same repo

The problem

Two Next apps in one repo look similar. Same folders, same tools. Different env needs. Copy .env.local from one app into another.

The shell loads. The first API call or redirect fails. AI assumes env is fine because the file is there.

The fix

Every app has its own .env.example. Start from that file every time.

Env is per app, not per repo.

14. Login page and dashboard on the same local port

The problem

Login usually lives on one app. The dashboard on another. In local dev that means different ports (for example 3001 for login, 3000 for dashboard).

If both URLs in env point to the same port, redirects get confused. Loops, wrong landing page, sign out going nowhere useful.

The fix

Write down the flow: login address → callback → dashboard address.

Set env to match separate apps, even on localhost.

15. Green code review, nobody ran a production build

The problem

AI fixed the component in the prompt. Types pass. Review looks good. Nobody ran a full production build with real login and a real API call.

The fix

Before merge:

next dev starts without warnings
next build passes with the same config CI uses
One real login (skip-login flag off)
One API call that returns real data

Conclusion

AI is strong inside a single file. It is weak on repo layout, env setup, static vs server deploy, and whether your GitHub branch matches your local branch.

Those live outside the chat window. Check them yourself and a lot of "random" Next.js bugs stop being random.

Need Help With Your Next.js or AWS Project?

Over the last 5+ years, I've helped build and maintain production systems used by businesses across different industries. If you're looking for help with:

Next.js applications
React architecture
AWS deployments
AI integrations
Performance optimization

feel free to reach out.

LinkedIn: Femi Akinyemi
DEV: dev.to/femi_akinyemi
Portfolio: Femi Akinyemi

Introduction

1. Next dev watching the whole monorepo

2. Putting server secrets in NEXT_PUBLIC_*

3. API address missing or duplicating /api/v1

4. Adding server API files to an app that deploys as static HTML

5. Local proxy setup that does not exist in production

6. Server-only code imported in a client component

7. Login token is valid but for the wrong app

8. Fake login still turned on while shipping real auth

9. Old dev server still running on the port

10. No conflict on your machine, conflict on GitHub

11. Expired login token in your env file

12. Public env vars set after the build, not during it

14. Login page and dashboard on the same local port

15. Green code review, nobody ran a production build

Conclusion

Need Help With Your Next.js or AWS Project?

2. Putting server secrets in `NEXT_PUBLIC_*`

3. API address missing or duplicating `/api/v1`

4. Adding server API files to an app that deploys as static `HTML`