Appearance

Language

Build a personal website from 0

Works Locally, Fails on Deploy? Why Website Deploys Break and How to Fix Them (2026)

Build fails on Vercel, Cloudflare or Netlify but works locally? Read the build log, reproduce cleanly and match it to the common causes, with real incidents.

Kelvin Wang · · 20 min read

Key points

  1. First work out which failure you have: no build was triggered, the build failed, or the build passed and the live site is broken. Each one is checked differently.
  2. In a build log, look for the first error, not the last line. The last line is usually just 'command exited with 1'.
  3. Most 'works on my machine' cases come from what your machine has that the builder doesn't: a .env file, caches, a case-insensitive file system, a different Node version. A clean clone running npm ci && npm run build is the closest you get to the builder.
  4. When an AI agent fixes a deploy, give it the full error, make it reproduce and name the cause before changing anything, and refuse fixes that turn off checks, add --force or delete tests.

You run npm run dev and everything works. You push to GitHub, the host starts a build, and it goes red. Or the build goes green, and the live site is blank, unstyled, or returns 404 when you refresh a page. Nearly every case comes down to one thing: the host’s build machine and runtime are not your computer. Whether the site was written with Claude Code, Cursor, v0 or Lovable, and wherever it is deployed, the way to track it down is the same.

My site is Astro on Cloudflare Workers, written with help from Claude Code. Since September 2026 I have run into the causes below seven times, and each time maps to a commit in the repo.

What’s actually different between your machine and the host?

The host grabs a clean copy of your code from GitHub on its own machine, installs packages from scratch and runs the build. Anything on your computer that isn’t in git, it doesn’t have. These differences cover almost every “works locally, fails on deploy”:

DifferenceYour computerThe host's builder
Environment variablesAll in your .env file.env isn't in git; if you didn't set it on the host, it isn't there
File name casemacOS and Windows ignore case by defaultLinux: Header.js and header.js are two files
Node versionWhatever you installedThe host's default, or the one you pin
Packagesnode_modules may be months oldFresh install from the lockfile
CachesLeft over from earlier buildsUsually empty, or the host's own build cache
ResourcesMemory and open files are generousCapped; going over fails or cancels the build
RuntimeNode.jsNode.js, or a slimmer runtime such as Workers or Edge

Vercel’s own guide traces the classic Module not found to case: Windows and macOS use case-insensitive file systems by default, and Vercel builds on a case-sensitive Linux file system4. Netlify’s docs say the same, and add that the resulting error may not make the cause obvious3.

Which kind of deploy failure is it?

“The deploy failed” covers three different situations, and each one is checked in a different place:

What you seeWhich kindLook here first
No new deployment shows up on the host after a pushNo build was triggeredThe host's Git connection and production branch setting
The deployment is red / FailedBuild failed; the old version is still liveThe build log
Deploy succeeded, but the site is wrong, blank, unstyled, or some pages 404Build passed, broken at runtimeBrowser DevTools (Console, Network) and the host's runtime logs

When a build fails, the site doesn’t go down: the host keeps serving the last good version. So “the site still loads” does not mean your change shipped. Another post covers how to confirm a deploy actually went live:

Go deeper What Breaks After You Launch an AI-Built Site: Failed Deploys, Leaked Keys, Database Permissions Why failed deploys are silent, how to confirm a deploy shipped, and how to roll back.

Go through it in this order:

  1. Check whether a build ran. If the host’s deployment list doesn’t have this commit, nothing was triggered. Here, retriggering is the right move, because there is no log to read.
  2. If the build failed, read the build log and find the first error (next section).
  3. Reproduce in a clean environment. Clone the repo fresh, leave out .env, and run npm ci && npm run build on the same Node version the host uses.
  4. If it reproduces, match it against the causes below. If it doesn’t, suspect a resource limit or a host setting.
  5. If the build passed but the site is broken, open DevTools and read the red lines in Console and Network, then the host’s runtime logs.
  6. After the fix, open the live page again. Don’t stop at a green build.

Symptom lookup table

What you seeMost likely causeDo this first
No new deployment after a pushNo build triggeredCheck the branch setting, retrigger
undefined or Invalid URL during the buildBuild has no environment variablesSet build variables on the host, redeploy
Module not found for a file that existsFile name caseCompare the import with the real name; rename with git mv
Unsupported engine, syntax errorsDifferent Node versionPin it with .nvmrc or the host setting
npm ci says the lockfile is out of syncpackage.json changed, lockfile didn'tnpm install locally, commit the lockfile
Build passes, site is 404 or blankWrong output directory or build commandCheck your framework's output folder
Flaky, with EMFILE or out of memoryBuilder resource limitsRead the log; reduce parallel file or memory use
The Console shows a variable as undefinedVariable lacks the browser prefixCheck the prefix, and that the variable isn't a secret
Requests go to localhostHard-coded URLUse an environment variable or a relative path
Some pages 500 as soon as they runRuntime lacks a Node APIRead runtime logs; reproduce with the host's local emulation
Refresh gives 404SPA without a rewriteAdd a rewrite or not_found_handling
Every CSS and JS file 404sBase path not setSet base or basePath
Mixed Content in the ConsoleHTTP resource on an HTTPS pageSwitch the URL to https
Unstyled right after deploy, fine laterA cache serving old HTMLCheck the CDN or your own cache

How do you read a build log?

Each host keeps the build log somewhere different:

HostWhere the build log is
VercelProject → Deployments → the failed deployment → expand Building under Deployment Details [1]
Cloudflare WorkersWorkers & Pages → your Worker → Deployments → View build history [2]; the check run next to the GitHub commit also shows pass or fail
NetlifyThe deploy log for that deploy, which records each step of the build and deploy and any errors [3]
GitHub PagesThe deployment's workflow run under the repo's Actions tab; both branch publishing and custom workflows deploy through a workflow run [22]

The way to read it is the same everywhere:

  1. Find the first red Error, ERR! or error, not the last line. Vercel’s docs use exactly this example: the last line says only yarn run build exited with 1, and the real cause is a few lines above1.
  2. Note which stage it is in: install, build, or deploy. Install failures are mostly the lockfile or the Node version. Build failures are mostly code, environment variables or file name case. Deploy failures are mostly host settings.
  3. Copy twenty or thirty lines around it. That block is what you search for, or hand to an AI.

Vercel also notes that some failures happen before the build starts, an invalid vercel.json for example. Then there’s no build log, and the error is shown in the dashboard instead1.

Why do builds fail?

The build can’t see your environment variables

Symptom: the build fails at the step that fetches data, with undefined, Invalid URL, supabaseUrl is required or similar, or an API returns 401.

Your machine has .env; the builder doesn’t. You have to enter each variable in the host’s settings. Two things are easy to miss:

  • Build-time and runtime variables can be separate. On Cloudflare Workers Builds, build variables go under Settings → Build → Build variables and secrets. Cloudflare’s docs say these aren’t accessible at runtime; runtime variables go under Settings → Variables & Secrets23. The reverse holds too: the Variables & Secrets block at the top of the same page is for runtime, and the build can’t read what you put there. I’ve put variables in the wrong block myself. My site’s first automatic build on Workers Builds failed on missing build variables: posts are read from Supabase at build time, the build had neither variable, and it passed once I added them under Settings → Build.
  • Changing a variable needs a new deploy. Vercel’s docs say environment variable changes apply only to new deployments; a running deployment keeps the values it was built with12. Vercel also separates Production, Preview and Development, so a variable set only for Production is missing on preview URLs12.
Go deeper Cloudflare Workers Tutorial 2026: Astro SSR and Wrangler Where build variables, runtime variables and secrets each go, with my real setup.

File name case doesn’t match

Symptom: Module not found, Cannot find module or Could not resolve, for a file you know exists.

The code says import Header from './components/Header'; the file is header.astro. macOS finds it; Linux doesn’t. It reproduces on a case-sensitive volume, where Node says:

Error [ERR_MODULE_NOT_FOUND]: Cannot find module '.../components/Header.js' imported from .../main.mjs

The same files run fine on a normal macOS volume. Each bundler words the error differently, but it means the same thing.

The fix has a trap: on macOS, changing only the case of a file name may not register with git. Vercel suggests git config core.ignorecase false, or renaming in two git mv steps through a temporary name4:

git mv components/header.astro components/header-tmp.astro
git mv components/header-tmp.astro components/Header.astro

Node or package manager versions differ

Symptom: the install step fails, mentioning engine or Unsupported engine, a syntax error, or a package that needs a newer Node.

Every host has a default Node version, and it may not be yours. When I checked in November 2026, Cloudflare Workers Builds defaulted to 24.22.16, and new Vercel projects default to the latest LTS Vercel offers, currently 26.x7. How to pin it:

HostHow to pin the Node version
VercelProject Settings → Build and Deployment → Node.js Version; engines.node in package.json overrides it [7]
Cloudflare Workers BuildsA NODE_VERSION build variable, or .nvmrc / .node-version in the root [6]
NetlifyA NODE_VERSION environment variable, or .node-version / .nvmrc; both override the UI setting [5]
GitHub Pages (Actions)The version in the workflow's setup-node step

Run node -v locally and pin the same major version in the project. The package manager matters too: hosts pick npm, pnpm or yarn from the lockfile in the repo65. If the repo has both package-lock.json and pnpm-lock.yaml, keep one.

The lockfile doesn’t match package.json

Symptom:

npm error `npm ci` can only install packages when your package.json and package-lock.json or npm-shrinkwrap.json are in sync. Please update your lock file with `npm install` before continuing.

Change package.json without updating the lockfile, run npm ci, and that’s what you get. Some hosts and CI setups install with npm ci (Cloudflare’s troubleshooting page lists this exact error2), which requires a lockfile that matches package.json and exits with an error instead of updating it8. The most common case: an AI added a package to package.json and never ran npm install, or ran it and didn’t commit the lockfile.

Fix: run npm install locally and commit the updated lockfile. If npm ci passes locally and fails only on Cloudflare, Cloudflare’s troubleshooting page says the lockfile was likely written by a newer npm than the build image uses. It ignores engines.npm; set packageManager in package.json to the exact version npm -v shows locally, for example "packageManager": "npm@11.19.1"2.

Packages that don’t agree on versions are a different error: Could not resolve dependency or Conflicting peer dependency. Netlify’s docs trace one version of this to a behaviour in npm 8.6 through 8.12.1, seen mostly on sites using React 17 or later with Node 16.5.1 or later, and suggest passing --force or --legacy-peer-deps through the NPM_FLAGS environment variable3. That’s a workaround for those npm releases. Used anywhere else, both flags just tell npm to ignore the conflict; the conflict stays, and that is exactly the kind of fix the AI section further down tells you to refuse. In my case (TypeScript 7 outside what @astrojs/check accepts), I pinned TypeScript to 6 so the versions actually match, rather than telling npm to ignore the conflict.

The build command or output directory is wrong

Symptom: the build passes, and the site is a 404, a blank page, or a raw file listing.

The host needs to know two things: which command builds the site, and which folder to publish afterwards. Vercel fills both in when it detects the framework, and serves only what’s in the output directory13. If detection is wrong, or your app isn’t at the repo root, set them yourself:

  • Output directory. dist for Astro and Vite, out for a Next.js static export.
  • Root Directory. Needed when the app lives in a subfolder such as web/.
  • Cloudflare Workers. Cloudflare’s troubleshooting page lists three causes for “build passed, site is 404 or blank”: the build command doesn’t run the framework build, assets.directory doesn’t point at the output folder, or a single-page app lacks not_found_handling2.

The builder runs out of resources

Symptom: it passes sometimes and fails other times, with EMFILE: too many open files, JavaScript heap out of memory, SIGKILL, or a cancelled build.

Cloud builders cap memory, open files and time. A Vercel build can run at most 45 minutes1; a Cloudflare Workers Build, 202. Mine was open files: Rollup opens up to 1,000 files at once by default, which was fine on my laptop and sometimes too many on Cloudflare’s builder (Cloudflare doesn’t publish that limit; that it’s lower than my laptop’s is inferred from the behaviour and a local reproduction). Lowering the limit locally with ulimit -Hn 512 reproduced it, and setting maxParallelFileOps to 64 fixed it. The full walkthrough is in the Workers tutorial, under debugging a failed deploy.

Why is the site broken when the build passed?

Environment variables missing in the browser, or leaking into it

Symptom: a feature does nothing, and the Console shows a variable as undefined.

Frontend frameworks only put variables with a certain prefix into browser code, and they write the value in at build time:

FrameworkPrefix that reaches the browserWhen the value is fixed
Next.jsNEXT_PUBLIC_Inlined during next build; later changes have no effect [9]
Vite (common for React and Vue apps)VITE_Statically replaced at build time [10]
AstroPUBLIC_Statically replaced at build time [11]

That has two consequences. Without the prefix, the variable is undefined in the browser, locally too, but you won’t notice if your local code happens to read it on the server. With the prefix, every visitor can see it, and Vite’s docs say outright that these variables shouldn’t hold secrets such as API keys10. An AI asked to “make it work” will sometimes add the prefix to a secret key. The feature works, and the key is public.

Next.js also only replaces process.env.NEXT_PUBLIC_XXX written out in full; a computed name such as process.env[name] isn’t inlined9.

The code still points at localhost

Symptom: in the Network tab on the live site, requests go to http://localhost:3000 or 127.0.0.1 and fail.

During development the API and database run on your machine, and AI-written code often hard-codes http://localhost:3000/api. Once deployed, a visitor’s browser calls localhost on the visitor’s own machine, where nothing is listening. Search the project for localhost and 127.0.0.1, and replace them with an environment variable or a relative path (/api/...).

The runtime isn’t Node.js

Symptom: the build passes, then some pages or API routes return 500; the logs mention a missing module, an unsupported API, or, in my case, Invalid redirect value.

Runtimes such as Vercel’s Edge and Cloudflare Workers are not full Node.js. Next.js’s docs say the Edge Runtime doesn’t support all Node.js APIs: no reading or writing the file system, and no calling require directly15. Cloudflare Workers needs nodejs_compat for Node APIs; it’s on by default for compatibility dates of 2026-08-04 or later, and opt-in before that16.

The worst part of this class of problem is that local tests don’t catch it, because tests run on Node. My OAuth incident was exactly that: every test passed, and every social sign-in request in production failed. After the fix I added a test that fails if redirect: 'error' ever appears in the source again. To get closer to production locally, use the host’s local emulation, such as Cloudflare’s wrangler dev or Vercel’s vercel dev.

The adapter you use for Next.js on Cloudflare matters here too. next-on-pages only supported the Edge runtime and was archived in October 2026. In 2023 it held me up when I took a Next.js project from 13 to 14, because it didn’t support the new version yet:

Go deeper Next.js on Cloudflare in 2026: What to Do Now That next-on-pages Is Deprecated The three routes after next-on-pages: vinext, OpenNext, static export.

The home page works, refreshing any other page is a 404

Symptom: clicking through to /about works; refreshing /about, or pasting the URL, gives a 404.

This is the classic single-page app (SPA) problem, common with React or Vue plus client-side routing. A click is handled by JavaScript in the browser; a refresh asks the server for /about, and the server only has index.html. The fix is to tell the host to serve index.html for paths it can’t find:

HostSetting
VercelIn vercel.json: "rewrites": [{ "source": "/(.*)", "destination": "/index.html" }] [19]
Cloudflare WorkersUnder assets in wrangler.jsonc: "not_found_handling": "single-page-application"; in wrangler.toml: not_found_handling = "single-page-application" [17]
NetlifyA _redirects line /* /index.html 200, usually the last rule [18]
GitHub PagesNo rewrite setting. Copy index.html to 404.html [20], which shows the page but still returns a 404 status, or switch to hash routing (/#/about)

If your site is mostly posts and pages, the more lasting fix is a framework that renders every page to HTML, which search engines also read more easily.

The base path is wrong

Symptom: deployed to https://username.github.io/repo-name/, the page loads but every CSS, JS and image file is a 404.

When a site lives under a subpath instead of the domain root, the framework has to know the prefix. Otherwise it looks for /assets/... while the files sit at /repo-name/assets/.... GitHub Pages project sites are exactly this case, and Vite’s docs say to set base to '/<REPO>/'14. Astro calls the setting base; Next.js calls it basePath. A custom domain or a username.github.io root site doesn’t need it.

An HTTPS page loads HTTP resources

Symptom: a Mixed Content warning in the Console, and an external script or API call is blocked, or the page loses styles or falls back to default fonts.

The live site is HTTPS, and somewhere in the code there’s an http:// URL. Browsers upgrade upgradable resources such as images to HTTPS automatically, and block scripts, fetch() calls, stylesheets loaded with <link> and web fonts outright21. That is why a page loads unstyled when an external CSS file or font comes in over http://. Developing on http://localhost hides this, so you only see it on the live site. Switch the URL to https://; if the other service doesn’t support HTTPS, replace it or proxy the request through your own server.

Styles disappear for a while after each deploy

Symptom: right after a deploy, some visitors get unstyled pages, or the Console shows Uncaught SyntaxError: Unexpected token; it clears up on its own later.

Build tools add a hash to CSS and JS file names (index.a1b2c3.js), and the names change with every build. If some cache layer still serves the old HTML, that HTML points at old file names the new deploy no longer has. Netlify’s docs put Unexpected token errors down to the same thing: a reference to an asset that’s no longer available, common with hashed file names or code splitting3. On my site the culprit was my own cache in the Worker; putting the build id in the cache key means a new deploy never gets old HTML.

How do you get an AI agent to fix a deploy without making it worse?

AI tools are good at reading error logs, but they can’t see your host’s dashboard and don’t know the Node version it runs. Short on facts, they guess, and a wrong guess turns into changes to unrelated things. Give the AI the facts in this order:

  1. Paste the full error block, twenty or thirty lines around it. Not just the last line, and not your own summary.
  2. Describe the environment: which host, which Node version, the build command, and whether a local build passes.
  3. Make it reproduce first and name the cause. For example: “in a clean clone without .env, run npm ci && npm run build.” It changes code only once the failure reproduces.
  4. Limit the scope: fix this error only. No package upgrades or restructuring on the side.
  5. Ask for a guard once it’s fixed, so the same failure can’t come back. My EMFILE fix was one config line plus a test that fails if the line disappears or the number is raised above 128.
  6. Open the live page yourself. Don’t stop at “fixed”.

Watch for “fixes” that make the error message disappear while the problem stays:

  • Turning off checks. Ignoring TypeScript or lint errors, skipping tests.
  • Forcing the install. --force or --legacy-peer-deps gets the install through, but the version conflict is still there and may break something else later.
  • Deleting or editing the failing test until it’s green.
  • Adding a public prefix to a secret so the frontend can read it.
  • Redeploying again and again in the hope the next run passes.

My site’s project instruction file (I use CLAUDE.md; Codex, Cursor and other tools read AGENTS.md or their own project rules) states how it deploys (a push to main deploys) and the manual fallback, so an AI starting work in the repo knows a push means production and where to check.

Go deeper AI Built My Website and I Don't Understand the Code. How Do I Keep Maintaining It in 2026? What goes in a project instruction file so AI tools know your deploy rules and checks.

The 7 times it happened to me

  • Harm done
  • Warning or reduced service
  1. Warning or reduced service: 2026-09-26

    npm ci failed to install

    TypeScript 7 fell outside the range @astrojs/check accepts; pinning it to ^6 fixed it (commit 8606f87).

  2. Harm done: 2026-09-29

    First automatic build on Workers Builds failed

    The build environment had no Supabase build variables. Once they were added, the README recorded that the build needs both (commit f5840c1).

  3. Warning or reduced service: 2026-10-06

    A package that would not have loaded on Workers

    When I added twitter-text, the punycode it imports would have resolved to a Node built-in that Cloudflare's runtime can't load, so an alias points it at the npm package (commit 354068c).

  4. Harm done: 2026-10-08

    All tests passed; every OAuth call in production failed

    Workers rejects redirect: 'error' in fetch (commit 1bca515).

  5. Warning or reduced service: 2026-10-25

    Pages lost their styles for a while after each deploy

    My own edge cache served the old HTML for up to 15 minutes (commit f8f3953).

  6. Warning or reduced service: 2026-10-30

    A push didn't trigger a build at all

    An empty commit retriggered it (commit 51eeb63).

  7. Harm done: 2026-11-05

    5 of 7 pushes failed to build

    EMFILE: too many open files; capping Rollup's parallel file operations fixed it (commit 44ec11e).

FAQ

If npm run dev works locally, will the deploy work?

Not necessarily. dev and a production build take different paths, and many errors only appear in the build. Run npm run build locally before deploying, then look at the result with your framework’s preview command. Vite notes that vite preview is only for previewing the build locally, not a production server14.

I changed an environment variable and nothing happened. Why?

Most hosts need a new deployment before a change takes effect, and variables used in the browser were written into the code at build time. After changing one, trigger a new deploy.

The build keeps failing. Should I roll back?

When a build fails, the last good version is still live, so there’s nothing to roll back. Rolling back is for a build that passed with a broken new version. How that works on Cloudflare Workers, and its limits, is in What Breaks After You Launch an AI-Built Site; on other hosts, check their deployment list.

Sources

  1. 1. Troubleshooting Build Errors · Vercel · checked 2026-11-16
  2. 2. Troubleshooting builds · Cloudflare · checked 2026-11-16
  3. 3. Build troubleshooting tips · Netlify · checked 2026-11-16
  4. 4. How do I resolve a 'module not found' error? · Vercel · checked 2026-11-16
  5. 5. Manage build dependencies · Netlify · checked 2026-11-16
  6. 6. Build image · Cloudflare · checked 2026-11-16
  7. 7. Supported Node.js versions · Vercel · checked 2026-11-16
  8. 8. npm ci · npm · checked 2026-11-16
  9. 9. How to use environment variables in Next.js · Next.js · checked 2026-11-16
  10. 10. Env Variables and Modes · Vite · checked 2026-11-16
  11. 11. Using environment variables · Astro · checked 2026-11-16
  12. 12. Environment variables · Vercel · checked 2026-11-16
  13. 13. Configuring a Build · Vercel · checked 2026-11-16
  14. 14. Deploying a Static Site · Vite · checked 2026-11-16
  15. 15. Edge Runtime · Next.js · checked 2026-11-16
  16. 16. Node.js compatibility · Cloudflare · checked 2026-11-16
  17. 17. Single Page Application (SPA) · Cloudflare · checked 2026-11-16
  18. 18. Rewrites and proxies · Netlify · checked 2026-11-16
  19. 19. Static Configuration with vercel.json · Vercel · checked 2026-11-16
  20. 20. Creating a custom 404 page for your GitHub Pages site · GitHub · checked 2026-11-16
  21. 21. Mixed content · MDN · checked 2026-11-16
  22. 22. Configuring a publishing source for your GitHub Pages site · GitHub · checked 2026-11-16
  23. 23. Configuration · Cloudflare · checked 2026-11-16

About the author

Kelvin Wang

Electrical engineer building tools with AI agents, sharing hands-on notes on engineering and investing.

More about me