"It Works Locally": Fixing the Last-Mile Deployment Gap

"But it works on my machine." Every developer has said it, and every founder has heard it right before a launch slips. Your app runs perfectly on localhost — pages load, the database responds, the API keys work — and then you deploy it and get a blank screen, a 500 error, or a login that silently fails. Nothing in your code changed. So what did?

The honest answer: your local machine is a carefully arranged environment that hides a dozen assumptions. Production strips those assumptions away. The gap between "works locally" and "works in production" is almost always one of five things, and none of them require rewriting your app.

Why local and production are different worlds

When you run npm run dev, you get a forgiving setup: a dev server that patches over errors, a local database on localhost, environment variables loaded from a .env file, and permissive networking because everything is on one machine. Production is stricter on every axis — a real build step, a remote database behind a firewall, secrets that live somewhere else, HTTPS everywhere, and a different Node version.

The bug was never in your code. It was in the assumptions your code made about its environment. Here are the five that break most often.

1. Environment variables that never made it over

This is the number-one cause, by a wide margin. Locally, your .env file quietly supplies the database URL, API keys, and secrets. That file is (correctly) gitignored, so it never gets deployed. Production has no idea those values exist.

Symptoms: undefined API keys, "cannot connect to database", auth that fails instantly, or features that work locally and throw in production.

The fix:

• Add every variable to your host's dashboard (Vercel, Netlify, Railway) or your server's environment config. Do not skip one because it "seems optional."
• Know your framework's public vs private rule. In Next.js, only variables prefixed NEXT_PUBLIC_ reach the browser; the rest stay server-side. Miss the prefix and a client-side call gets undefined.
• Rebuild after changing them. Build-time variables are baked in at build, so a change without a redeploy does nothing.

A two-minute audit — diff your local .env keys against the ones set in your host — catches most "works locally" failures before they start.

2. The build step you never ran locally

In development you run a dev server. In production you run a real build (npm run build) that minifies, tree-shakes, and type-checks. Code that the dev server tolerated can fail the build outright.

Common culprits:

That third row bites constantly. Your Mac treats ./Header and ./header as the same file; the Linux server that hosts your app does not. Always run npm run build locally before you deploy — if it fails on your machine, it will fail in the cloud, and you would rather find out now.

3. Database URLs and connections

Locally you point at a database on localhost with no SSL and no connection limits. Production points at a managed database — Supabase, Neon, RDS — that lives behind a network boundary, often requires SSL, and caps concurrent connections.

What breaks:

• Connection strings. The localhost URL is meaningless in production. Set the real DATABASE_URL as an environment variable (see item 1).
• SSL requirements. Managed Postgres usually demands SSL. Your local connection did not, so your client config never enabled it.
• Connection pooling. Serverless functions (Vercel, Lambda) can open a flood of connections and exhaust the limit. Use a pooler — Supabase's pooling endpoint or PgBouncer — instead of direct connections.
• Migrations. Your local schema might be ahead of production. If you changed the schema and never ran the migration against the production database, queries reference columns that do not exist yet.

4. CORS, cookies, and the HTTPS boundary

Locally, your frontend and backend both run on localhost, so the browser treats them as friendly. In production they often live on different domains, and the browser's security model gets strict.

The usual suspects:

• CORS errors. Your API must explicitly allow your frontend's production origin. localhost:3000 in your allow-list does nothing for app.yourdomain.com.
• Cookies not sticking. Auth cookies frequently need Secure and SameSite set correctly for cross-site HTTPS. Locally over HTTP the rules are looser, so login "works" locally and breaks live.
• Mixed content. A production page served over HTTPS will block requests to an HTTP API. Every external call has to be HTTPS.
• Hardcoded URLs. http://localhost:8000 baked into your frontend is the most common single line that ships to production and immediately fails. Use an environment variable for the API base URL.

5. Node version and platform drift

Your laptop runs Node 20; the host defaults to Node 18. A syntax feature or dependency that works locally throws in production. Pin your version explicitly — set the engines field in package.json and, where supported, a .nvmrc — so local and production run identical runtimes. The same discipline applies to any build tool version your app depends on.

The last-mile deployment checklist

Before every deploy, walk this list. It takes ten minutes and saves the 2 a.m. debugging session:

1. Every .env key is set in the production host, with correct public/private prefixes.
2. npm run build passes cleanly on your own machine.
3. Production DATABASE_URL is set, SSL is enabled, and migrations have run.
4. CORS allows your real production origin; cookies use Secure/SameSite.
5. No hardcoded localhost URLs anywhere in the frontend.
6. Node version is pinned and matches the host.
7. You have checked the production logs after deploy — not just the homepage.

If you want a deeper safety net, our guide on taking a vibe-coded MVP to production covers the structural work that prevents these gaps from reappearing.

Frequently asked questions

Why does my app work locally but show a blank screen in production? Almost always a build error or a missing environment variable. Open the browser console and your host's deploy logs — the real error is there, even though the page looks empty.

How do I debug a production-only error I can't reproduce? Reproduce production conditions locally: run npm run build then npm start instead of the dev server, and point at a staging database with the same settings. Most "only in production" bugs appear the moment you stop using the dev server.

Is this worth paying someone to fix? If a launch is blocked and every hour of downtime costs you customers, yes. A last-mile deployment gap is usually a few hours of focused work for someone who has closed it a hundred times.

---

Stuck at the last mile with an app that runs fine locally but won't behave in production? SprintX fixes deployment gaps every week — env, build, database, and networking — with a fixed-scope quote and no lock-in. Tell us what's breaking and we'll get you live.