Why Your Next.js App Works Locally but Breaks in Production

Start by classifying the failure: build-time, server runtime, browser runtime, or deployment routing. That one distinction prevents hours of checking the wrong layer.

Compare the environment deliberately

• Confirm every required variable exists in the deployment environment and uses the correct public/server prefix.
• Check the Node.js version and runtime selected by the host.
• Verify the production build can reach the same API, database, and asset origins.
• Test the exact deployed route, not only the homepage.

// Server-only secret: never prefix with NEXT_PUBLIC_
const apiKey = process.env.INTERNAL_API_KEY;

Check build-time versus request-time data

A value read during a static build will not change at request time unless the route is configured to revalidate or render dynamically. Log the build result and the server result separately.

Evidence first

Read deployment logs, response headers, and the browser console together. “It works locally” is a comparison, not a diagnosis.

Audit server/client boundaries

Browser APIs belong in client components. Secrets and private fetches belong on the server. A boundary that is tolerated by local development can fail during an optimized build.

Still stuck with a React or Next.js bug? See React & Next.js debugging help.

Related notes

How to Fix Hydration Errors in Next.js
React Component Not Re-rendering? Common Causes