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
- 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.
- In a build log, look for the first error, not the last line. The last line is usually just 'command exited with 1'.
- 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.
- 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”:
| Difference | Your computer | The host's builder |
|---|---|---|
| Environment variables | All in your .env file | .env isn't in git; if you didn't set it on the host, it isn't there |
| File name case | macOS and Windows ignore case by default | Linux: Header.js and header.js are two files |
| Node version | Whatever you installed | The host's default, or the one you pin |
| Packages | node_modules may be months old | Fresh install from the lockfile |
| Caches | Left over from earlier builds | Usually empty, or the host's own build cache |
| Resources | Memory and open files are generous | Capped; going over fails or cancels the build |
| Runtime | Node.js | Node.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 see | Which kind | Look here first |
|---|---|---|
| No new deployment shows up on the host after a push | No build was triggered | The host's Git connection and production branch setting |
| The deployment is red / Failed | Build failed; the old version is still live | The build log |
| Deploy succeeded, but the site is wrong, blank, unstyled, or some pages 404 | Build passed, broken at runtime | Browser 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:
- 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.
- If the build failed, read the build log and find the first error (next section).
- Reproduce in a clean environment. Clone the repo fresh, leave out
.env, and runnpm ci && npm run buildon the same Node version the host uses. - If it reproduces, match it against the causes below. If it doesn’t, suspect a resource limit or a host setting.
- 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.
- After the fix, open the live page again. Don’t stop at a green build.
Symptom lookup table
| What you see | Most likely cause | Do this first |
|---|---|---|
| No new deployment after a push | No build triggered | Check the branch setting, retrigger |
undefined or Invalid URL during the build | Build has no environment variables | Set build variables on the host, redeploy |
Module not found for a file that exists | File name case | Compare the import with the real name; rename with git mv |
Unsupported engine, syntax errors | Different Node version | Pin it with .nvmrc or the host setting |
npm ci says the lockfile is out of sync | package.json changed, lockfile didn't | npm install locally, commit the lockfile |
| Build passes, site is 404 or blank | Wrong output directory or build command | Check your framework's output folder |
Flaky, with EMFILE or out of memory | Builder resource limits | Read the log; reduce parallel file or memory use |
The Console shows a variable as undefined | Variable lacks the browser prefix | Check the prefix, and that the variable isn't a secret |
| Requests go to localhost | Hard-coded URL | Use an environment variable or a relative path |
| Some pages 500 as soon as they run | Runtime lacks a Node API | Read runtime logs; reproduce with the host's local emulation |
| Refresh gives 404 | SPA without a rewrite | Add a rewrite or not_found_handling |
| Every CSS and JS file 404s | Base path not set | Set base or basePath |
Mixed Content in the Console | HTTP resource on an HTTPS page | Switch the URL to https |
| Unstyled right after deploy, fine later | A cache serving old HTML | Check the CDN or your own cache |
How do you read a build log?
Each host keeps the build log somewhere different:
| Host | Where the build log is |
|---|---|
| Vercel | Project → Deployments → the failed deployment → expand Building under Deployment Details [1] |
| Cloudflare Workers | Workers & Pages → your Worker → Deployments → View build history [2]; the check run next to the GitHub commit also shows pass or fail |
| Netlify | The deploy log for that deploy, which records each step of the build and deploy and any errors [3] |
| GitHub Pages | The 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:
- Find the first red
Error,ERR!orerror, not the last line. Vercel’s docs use exactly this example: the last line says onlyyarn run build exited with 1, and the real cause is a few lines above1. - 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.
- 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.
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:
| Host | How to pin the Node version |
|---|---|
| Vercel | Project Settings → Build and Deployment → Node.js Version; engines.node in package.json overrides it [7] |
| Cloudflare Workers Builds | A NODE_VERSION build variable, or .nvmrc / .node-version in the root [6] |
| Netlify | A 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.
distfor Astro and Vite,outfor 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.directorydoesn’t point at the output folder, or a single-page app lacksnot_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:
| Framework | Prefix that reaches the browser | When the value is fixed |
|---|---|---|
| Next.js | NEXT_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] |
| Astro | PUBLIC_ | 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:
| Host | Setting |
|---|---|
| Vercel | In vercel.json: "rewrites": [{ "source": "/(.*)", "destination": "/index.html" }] [19] |
| Cloudflare Workers | Under assets in wrangler.jsonc: "not_found_handling": "single-page-application"; in wrangler.toml: not_found_handling = "single-page-application" [17] |
| Netlify | A _redirects line /* /index.html 200, usually the last rule [18] |
| GitHub Pages | No 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:
- Paste the full error block, twenty or thirty lines around it. Not just the last line, and not your own summary.
- Describe the environment: which host, which Node version, the build command, and whether a local build passes.
- Make it reproduce first and name the cause. For example: “in a clean clone without
.env, runnpm ci && npm run build.” It changes code only once the failure reproduces. - Limit the scope: fix this error only. No package upgrades or restructuring on the side.
- 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.
- 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.
--forceor--legacy-peer-depsgets 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.
The 7 times it happened to me
- Harm done
- Warning or reduced service
-
Warning or reduced service: 2026-09-26
npm cifailed to installTypeScript 7 fell outside the range
@astrojs/checkaccepts; pinning it to^6fixed it (commit8606f87). -
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). -
Warning or reduced service: 2026-10-06
A package that would not have loaded on Workers
When I added
twitter-text, thepunycodeit 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 (commit354068c). -
Harm done: 2026-10-08
All tests passed; every OAuth call in production failed
Workers rejects
redirect: 'error'infetch(commit1bca515). -
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). -
Warning or reduced service: 2026-10-30
A push didn't trigger a build at all
An empty commit retriggered it (commit
51eeb63). -
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 (commit44ec11e).
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. Troubleshooting Build Errors
- 2. Troubleshooting builds
- 3. Build troubleshooting tips
- 4. How do I resolve a 'module not found' error?
- 5. Manage build dependencies
- 6. Build image
- 7. Supported Node.js versions
- 8. npm ci
- 9. How to use environment variables in Next.js
- 10. Env Variables and Modes
- 11. Using environment variables
- 12. Environment variables
- 13. Configuring a Build
- 14. Deploying a Static Site
- 15. Edge Runtime
- 16. Node.js compatibility
- 17. Single Page Application (SPA)
- 18. Rewrites and proxies
- 19. Static Configuration with vercel.json
- 20. Creating a custom 404 page for your GitHub Pages site
- 21. Mixed content
- 22. Configuring a publishing source for your GitHub Pages site
- 23. Configuration
Kelvin Wang
Electrical engineer building tools with AI agents, sharing hands-on notes on engineering and investing.
More about me