Start a project
Why My Green Vercel Deployment Returned a 404
Advanced

Why My Green Vercel Deployment Returned a 404

Updated 2 weeks ago3 min read
Project:Webshastraa Dashboard
Stack:
Next.jsVercelLinuxBashCI/CD

Vercel displayed a green deployment success badge, but my live production URL returned a pristine 404 Not Found. After five hours of debugging, I discovered the real culprit wasn't Next.js or Vercel—it was an AI-generated build command that silently deployed nothing.

In my previous engineering journal, I highly recommended using the bash && operator (npm run lint && next build) as a hard gatekeeper to prevent bad code from reaching production. If the linter fails, the build stops. It is a foolproof system.
Or so I thought, until I handed the deployment configuration over to an autonomous AI coding agent.
I was spinning up a new administrative dashboard for Webshastraa. To save time, I instructed the AI agent to containerize the build scripts and ship the code directly to my GitHub repository connected to Vercel.
The AI shipped the code. The Vercel webhook fired. I watched the Vercel dashboard as the deployment ran. The terminal output looked clean, and three minutes later, Vercel proudly displayed a massive green "Ready" badge. The production deployment was mathematically successful.
I clicked the live URL.
The screen flashed, and rendered a pristine, unstyled standard server message:
404: NOT_FOUND
What followed was a brutal, 5-hour debugging session that taught me exactly how Vercel interprets Linux exit codes, why AI agents are dangerously literal, and how a deployment can be simultaneously successful and entirely empty.
---

1. The 5-Hour Debugging Descent

When you push a Next.js application to Vercel and receive a green success badge, you inherently trust that the application compiled correctly. If a URL returns a 404, your brain immediately assumes it is a routing problem, not an infrastructure problem.

Assumption 1: Next.js Routing is Broken

I opened my local code editor to investigate the codebase.
  • Did the AI accidentally delete app/page.tsx? No, the file was sitting right there.
  • Was there a syntax typo in the route grouping? No.
  • Did it compile locally? Yes, running npm run dev worked perfectly on my machine.

Assumption 2: Middleware is Blocking the Request

Perhaps the AI wrote a strict Edge Middleware file that was incorrectly intercepting the root path and returning a 404. I checked middleware.ts. It was perfectly standard. I even deleted the file and triggered a manual redeployment just to be absolutely safe.
Vercel showed another green success badge. The URL still showed a 404.

Assumption 3: Build Output Directory Mismatch

Sometimes, if you override the Next.js config, Vercel looks for the built files in the wrong directory (e.g., looking for a .next folder but the framework exported to a static out folder). I checked the Vercel project settings in the dashboard. Everything was perfectly set to the Next.js defaults.
I was three hours deep into debugging. The routing was flawless. The code was perfect. Vercel was screaming that the deployment was successful. Yet, the internet insisted the website did not exist.
---

2. The Discovery: Downloading the Artifact

I decided to stop looking at the React code and start looking at the cloud infrastructure.
In the Vercel dashboard, there is a small, often ignored feature hidden in the deployment summary menu: Download Output. This allows you to download the actual, physical ZIP file of the compiled static assets that Vercel is serving to its global edge network.
I clicked the download button. The ZIP file instantly saved to my desktop.
The file size was exactly 0 Bytes.
I unzipped it. It was completely empty.
Vercel had not deployed a broken website. It had deployed nothing. Because the server was hosting an entirely empty folder, visiting the root URL naturally returned a 404 Not Found.
The mystery shifted immediately: How did Vercel successfully deploy an empty folder without throwing a red "Build Failed" error?
---

3. The AI's Lethal Linux Mistake

I opened the deployment configuration files the AI had generated in the repository. Instead of just editing the package.json, the AI had decided to be "helpful" and created a custom Linux bash script (build.sh) to handle the pipeline.
Here is the exact code the AI shipped:

💡 Key Engineering Takeaways

A green checkmark in Vercel only means the build script exited with code 0; it does not guarantee a successful build. AI coding agents often mishandle Linux shell execution contexts when generating custom CI/CD build scripts. An empty deployment occurs when a build fails silently, causing Vercel to serve an empty output directory.

Frequently Asked Questions

What exactly is a Vercel empty deployment?

An empty deployment occurs when Vercel's build engine receives a successful exit code (Exit 0) from your build script, but the actual compilation step was skipped or failed silently. Vercel packages the empty output directory and deploys it to the edge, resulting in a live URL that returns a 404 Not Found error.

Why did the `&&` operator cause the build to skip?

In a Linux shell environment, the `&&` (Logical AND) operator ensures the second command only runs if the first command succeeds. Because `npm run lint` failed due to a code warning, the shell short-circuited and completely bypassed the `npm run build` command, leaving the output folder empty.

Why did Vercel think the deployment was successful if the build skipped?

Vercel determines success purely by the final exit code of the execution step. Because the AI placed the `&&` command inside a bash script without a strict error-handling flag, the bash script continued executing subsequent commands (like `echo`). The script finished successfully, returning an Exit 0 to Vercel, masking the earlier failure.

What does the `set -e` command do in a Linux bash script?

The `set -e` command is a vital safety mechanism in CI/CD pipelines. It instructs the bash shell to exit immediately with a non-zero status if any individual command or pipeline within the script fails. This prevents subsequent commands from running and ensures Vercel catches the error and halts the deployment.

How can I verify if my deployment is empty?

If you suspect an empty deployment, go to your Vercel project dashboard, click on the specific deployment, click the vertical three dots (options menu) in the deployment summary, and select "Download Output". If the downloaded ZIP file is empty or missing your static HTML/JS assets, your build command failed silently.

What exactly is a Vercel empty deployment?

An empty deployment occurs when Vercel's build engine receives a successful exit code (Exit 0) from your build script, but the actual compilation step was skipped or failed silently. Vercel packages the empty output directory and deploys it to the edge, resulting in a live URL that returns a 404 Not Found error.

Why did the `&&` operator cause the build to skip?

In a Linux shell environment, the `&&` (Logical AND) operator ensures the second command only runs if the first command succeeds. Because `npm run lint` failed due to a code warning, the shell short-circuited and completely bypassed the `npm run build` command, leaving the output folder empty.

Why did Vercel think the deployment was successful if the build skipped?

Vercel determines success purely by the final exit code of the execution step. Because the AI placed the `&&` command inside a bash script without a strict error-handling flag, the bash script continued executing subsequent commands (like `echo`). The script finished successfully, returning an Exit 0 to Vercel, masking the earlier failure.

What does the `set -e` command do in a Linux bash script?

The `set -e` command is a vital safety mechanism in CI/CD pipelines. It instructs the bash shell to exit immediately with a non-zero status if any individual command or pipeline within the script fails. This prevents subsequent commands from running and ensures Vercel catches the error and halts the deployment.

How can I verify if my deployment is empty?

If you suspect an empty deployment, go to your Vercel project dashboard, click on the specific deployment, click the vertical three dots (options menu) in the deployment summary, and select "Download Output". If the downloaded ZIP file is empty or missing your static HTML/JS assets, your build command failed silently.

What exactly is a Vercel empty deployment?

An empty deployment occurs when Vercel's build engine receives a successful exit code (Exit 0) from your build script, but the actual compilation step was skipped or failed silently. Vercel packages the empty output directory and deploys it to the edge, resulting in a live URL that returns a 404 Not Found error.

Why did the `&&` operator cause the build to skip?

In a Linux shell environment, the `&&` (Logical AND) operator ensures the second command only runs if the first command succeeds. Because `npm run lint` failed due to a code warning, the shell short-circuited and completely bypassed the `npm run build` command, leaving the output folder empty.

Why did Vercel think the deployment was successful if the build skipped?

Vercel determines success purely by the final exit code of the execution step. Because the AI placed the `&&` command inside a bash script without a strict error-handling flag, the bash script continued executing subsequent commands (like `echo`). The script finished successfully, returning an Exit 0 to Vercel, masking the earlier failure.

What does the `set -e` command do in a Linux bash script?

The `set -e` command is a vital safety mechanism in CI/CD pipelines. It instructs the bash shell to exit immediately with a non-zero status if any individual command or pipeline within the script fails. This prevents subsequent commands from running and ensures Vercel catches the error and halts the deployment.

How can I verify if my deployment is empty?

If you suspect an empty deployment, go to your Vercel project dashboard, click on the specific deployment, click the vertical three dots (options menu) in the deployment summary, and select "Download Output". If the downloaded ZIP file is empty or missing your static HTML/JS assets, your build command failed silently.

Feedback

Was this article helpful?

Related Engineering Diaries