Full-Stack Development · Tutorial 12 of 12
Fix a Failed Deployment: build errors, environment variables and the wrong root folder
By the FUTEAC Team · 19 November 2026 · 13 min read · Beginner
In short
A failed deployment is one of three things: the build broke, an environment variable is missing, or the host is looking in the wrong folder. The deploy log names the cause. This tutorial reproduces all three failures, fixes each one, and ends with a check that proves the deploy worked.
- Read the first error, not the last line. A deploy log is long, and the last lines are usually just the summary. The cause sits at the first line marked
error. - A deployment is three steps, and each step fails differently. Install, build, then run. Knowing which step failed tells you where to look.
- Your laptop is not the server. Code that works locally fails on a host when a setting lives only on your machine, in a
.envfile the host never sees. - The build is a check, not the enemy. Silencing it makes the deploy go green and ships a broken app.
- This tutorial feeds the Node & Express API Foundations course (/course/node-express-api-foundations) and the Deployment (/skill/deployment) skill.
Before you start
What does a failed deployment look like?
You push to GitHub, the host starts a deploy, and a minute later the dashboard shows a red Failed badge. Your app is not live, and nothing you change in the browser will fix it, because the problem is in the deploy, not in the page.
A deploy has three steps, in order. First the host installs your dependencies with npm install. Then it builds your app with the build command, usually npm run build. Then it starts the app with the start command, usually npm start or node server.js. Each step can fail, and each failure looks different.
Think of it like a recipe with three stages: shop, cook, serve. If the shopping fails, you never get to cook. If the cooking fails, there is nothing to serve. Reading the log means finding which stage stopped, then reading the first error in that stage.
Open the deploy log and search for the word error. Ignore the warnings above it; warnings do not stop a deploy. The first line with error in it is the cause. Everything after it is the consequence. That one habit solves half of all failed deploys, because beginners usually read the last ten lines, which only say the deploy failed, and never scroll up to the line that says why.
---
Failure 1: the build error
The most common build failure is a TypeScript error. Your code runs fine on your laptop because you never ran the build there, or you ran it before the mistake was added. The host runs the build every time, and TypeScript stops it at the first error.
Here is a small project that reproduces it. The file app.ts imports from a file that does not exist:
import { missing } from "./missing";
console.log(missing);The package.json runs TypeScript as its build step:
{
"name": "my-app",
"version": "1.0.0",
"scripts": {
"build": "tsc --noEmit"
}
}TypeScript also needs a config file, or it prints its help text instead of checking your code. Add tsconfig.json:
{
"compilerOptions": { "target": "es2022", "module": "commonjs", "strict": true },
"include": ["app.ts"]
}Then install TypeScript, pinned to the version this tutorial was tested with, and run the build locally, exactly as the host will:
npm install -D typescript@5.9.3
npm run buildIt fails with exit code 2, and this is the error:
app.ts(1,25): error TS2307: Cannot find module './missing' or its corresponding type declarations.Read it piece by piece. app.ts(1,25) is the location: file app.ts, line 1, column 25. TS2307 is the error code, and you can search it. Cannot find module './missing' or its corresponding type declarations is the cause: the import points at a file that is not there.
The fix is to make the import true. Either create the missing file:
export const missing = "found";Or fix the import to point at a file that exists. Then run the build again:
npm run buildThis time it prints nothing and exits 0. Silence plus exit code 0 is a passing TypeScript build, and that is what the host needs to see.
Two rules follow from this. First, run npm run build on your own machine before every push. If it fails at home, it will fail on the host, and finding out at home costs you seconds instead of a deploy cycle. Second, never push code you have only run with ts-node or a dev server. A dev server is forgiving about things a production build is strict about, and the host runs the strict one.
---
Failure 2: the missing environment variable
An environment variable is a setting that lives on the server, not in your code. Database passwords, API keys and secret tokens all belong there, because code goes to GitHub and settings must not. The trap is that your laptop has the setting and the host does not, because the setting lives in a .env file that Git ignores.
Here is a tiny server that needs a database URL:
const url = process.env.DATABASE_URL;
if (!url) {
console.error("Missing environment variable: DATABASE_URL");
process.exit(1);
}
console.log("Connected with:", url.split("@")[1]);Run it with no variable set, which is exactly the state of a fresh deploy:
node server.jsIt prints the error and exits 1:
Missing environment variable: DATABASE_URLSet the variable and run it again:
DATABASE_URL="postgres://user:pass@localhost:5432/mydb" node server.jsNow it prints Connected with: localhost:5432/mydb and exits 0. The code never changed. The only difference is the setting.
The fix on the host is the same idea, done in the dashboard. In Vercel, open Project Settings, then Environment Variables, add DATABASE_URL with the real value, and redeploy. The redeploy matters: a deploy reads the variables when it starts, so a variable added after a deploy does not reach the app that is already running. Change the setting, then deploy again.
Two rules here as well. First, keep a list of every variable your app reads, and check it against the dashboard before you deploy. A common shape is a .env.example file in the repo that lists the names with fake values, so the list is visible and the secrets stay out. Second, never paste a real secret into code or into a chat message to get it onto the server. Type it into the dashboard, where it is stored as a secret.
---
Failure 3: the wrong root folder
The third failure looks strange the first time you see it: the host says it cannot find your package.json, even though the file is right there in your repo. It is right there, but the host is looking in the wrong folder.
This happens when the code lives in a subfolder. A common layout is a repo with my-app/ inside it, and package.json inside my-app/. If the host is told the project root is the repo root, it looks for package.json there, does not find it, and the deploy dies before it starts.
Run the build from the parent folder to see the exact error:
npm run buildnpm error code ENOENT
npm error syscall open
npm error path /tmp/deploy-test/package.json
npm error errno -2
npm error enoent Could not read package.json: Error: ENOENT: no such file or directory, open '/tmp/deploy-test/package.json'ENOENT is the operating system saying "no such file". The path in the message tells you where it looked. If that path is the repo root and your package.json is one folder down, you have found the problem.
The fix is a setting, not code. In Vercel, open Project Settings, then General, and set Root Directory to the folder that holds package.json, for example my-app. Then redeploy. The same setting exists on other hosts under names like "base directory" or "app root", and the idea is identical: point the host at the folder that holds your package.json.
A quick way to catch this before you deploy is to ask yourself one question after every push: if I cloned this repo fresh and ran npm install in the folder the host uses, would it work? If the answer needs a cd first, the root folder setting is wrong.
---
The wrong turn: silencing the build so the deploy goes green
When the build keeps failing, the tempting fix is to make the build do nothing. Change the build command in package.json to this:
{
"scripts": {
"build": "echo build-ok"
}
}Run it:
npm run buildbuild-okIt exits 0. Push it, and the deploy goes green. The app is live. And the app is broken, because the TypeScript error is still in the code, and the page that uses the missing import now crashes in the browser instead of at build time.
The build is a smoke alarm, not the fire. Taking the battery out stops the noise and leaves the smoke. When a build fails, the fix is in the code the error names, never in the command that runs the check. If you ever catch yourself editing the build command to get past an error, stop: you are hiding the problem from the one tool that found it.
---
A checklist: error text, cause, fix
| What the log says | What it means | Fix |
|---|---|---|
error TS2307: Cannot find module './missing' | An import points at a file that does not exist | Create the file or fix the import, then run npm run build locally until it exits 0 |
Missing environment variable: DATABASE_URL (or the app crashes on undefined) | A setting exists on your laptop but not on the host | Add it in Project Settings, Environment Variables, then redeploy |
npm error enoent Could not read package.json | The host is looking in the wrong folder | Set Root Directory to the folder holding package.json, then redeploy |
npm error code ELIFECYCLE with a failing command | The install or build step itself crashed | Read the lines above it for the real error, usually one of the three rows above |
| Deploy succeeds but the page shows an error | The app started, then crashed at runtime | Check the runtime logs, not the build log, and look for a missing variable first |
---
How to verify the fix worked
Do not trust the green badge alone. Run this check after every fix:
- Run
npm run buildon your laptop. It must exit 0 with no errors. - Push, and watch the deploy log until it says the deploy finished. Open the log and confirm there is no line marked
error. - Open the live URL in a browser. The page must load, not show an error screen.
- Click the one feature that needs the server, for example a login or a list that comes from the database. If it loads real data, the variables and the database connection are right.
- Check the runtime logs for the first minute after the deploy. No errors there means the app is not just built, it is running.
If all five pass, the deploy is fixed. If step 3 or 4 fails while the deploy is green, the problem is at runtime, and the missing-variable section is where to look first.
---
Try it yourself
Take a small Node project you have already built, one with a package.json and a build script, and break its deploy on purpose, three times, fixing it each time: 1. In one file, change an import to point at a file that does not exist. Run npm run build. Read the first error line. Fix the import and run the build again until it exits 0. 2. In the same project, read a variable from process.env and print a clear message when it is missing. Run the app without the variable, watch it exit 1, then run it with the variable set and watch it work. 3. Move the whole project one folder down inside a new folder, so package.json is no longer at the top. Run npm run build from the top folder and read the ENOENT error. Then run it from the right folder and see it pass. If you do all three, you have seen every failure in this tutorial with your own eyes, and the next time a deploy goes red you will know which row of the checklist to reach for.
Continue in the free course: Node & Express API Foundations →
Common mistakes
- Pushing again without reading the log. A second push runs the same deploy and fails the same way. The log is the only thing that changes the outcome.
- Reading the last lines instead of the first error. The end of the log says the deploy failed. The cause is at the first line marked
error, usually far above it. - Committing your
.envfile to fix a missing variable. That puts a real secret on GitHub, where it stays in the history even if you delete the file later. Set the variable in the dashboard instead. - Setting the variable and forgetting to redeploy. A deploy reads its variables when it starts. A variable added afterwards waits for the next deploy.
- Fixing the symptom in the dashboard instead of the code. Editing a build command or deleting the file that errors gets the deploy green and ships the bug to your users.
- Assuming a green deploy means a working app. A deploy can pass while the app crashes on its first request, usually because a variable is missing at runtime. Open the live URL and the runtime logs, not just the deploy badge.
Frequently asked questions
Why does my app work on my laptop but fail when I deploy it?
Because your laptop and the host are different machines. Your laptop has your .env file, your global tools, and the folder layout you set up by hand. The host starts from a fresh clone of your repo and only what is in the repo, plus the settings in the dashboard. Anything that lives only on your laptop is missing on the host.
The log is hundreds of lines long. Where do I actually look?
Search for the word error. The first match is usually the cause. Read the ten lines above it for context, and ignore everything after the first error, because later lines are the knock-on effects of the first failure.
I fixed the problem. Why is the deploy still failing?
Check two things. First, did you push the fix? The host deploys what is on GitHub, not what is on your laptop. Second, did you redeploy after changing a dashboard setting? Environment variables and the root directory only take effect on the next deploy.
Should I use the host's "ignore build step" or "skip build" option?
No, not to get past an error. That option exists for projects that genuinely have nothing to build, like a plain HTML site. If your project has a build step, skipping it hides real errors, and the app you ship is the one that would have failed.
My deploy passed, but the page shows "Application error". What now?
That is a runtime failure, not a build failure, so the deploy log will not help. Open the runtime logs in the dashboard and look for the first error after startup. Nine times out of ten it is a missing environment variable or a database the app cannot reach.
Follow the Full-Stack Developer Roadmap
Build complete web applications, frontend, backend APIs, databases and deployment. Free, step by step, at your pace.
View the Roadmap