Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 37 ยท Deployments and Git Integration

Deploy Anatomy, Logs and Rollbacks

Learn the phases of a deploy, how to read build logs and fix common failures, and how to undo a bad release on Vercel and Netlify with instant rollback and deploy hooks.

A deploy that fails is normal; a deploy that you cannot diagnose is a problem. This lesson shows you what a deploy is made of, how to read the log without panic, and how to undo a bad release in seconds.

The two platforms use different words but the same mechanism: every deploy is an immutable snapshot, and "live" is just a pointer to one of them. Moving the pointer back is the fastest recovery there is.

The phases of a build

A build log is a story with chapters. Look for these headings:

  1. Initializing. The build container starts and the commit is cloned.
  2. Restoring cache. Previously saved dependencies are restored (see Build Caching).
  3. Installing dependencies. npm ci, npm install, yarn, pnpm install, depending on your lockfile.
  4. Building. Your build command and its output.
  5. Collecting output and functions. Static files and function bundles are gathered.
  6. Uploading and deploying. New files go to the CDN; unchanged ones are reused.
  7. Post-processing. Redirect and header rules are processed, then the deploy is marked ready.

The failing line is usually near the first line containing error, but the real cause can sit above it. Read upward from the red text.

Common failures and their usual causes

Symptom in the log Likely cause
command not found: vite The dependency is missing from package.json, or only installed globally on your machine
Cannot find module './Header' File-name case mismatch (Linux is case-sensitive)
Module not found after adding a package Lockfile not committed or out of sync
Build passes locally, fails remotely Different Node version or a missing environment variable
Exit code 137 or "killed" The build ran out of memory
"Build exceeded maximum duration" The build is too slow for your plan limit
Warnings treated as errors A CI setting (CI=true) makes some tools stricter

Both platforms set CI=true, and many tools (such as older Create React App) then fail on lint warnings. Fix the warnings or adjust your build script rather than disabling checks.

Node.js Build log triage (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Reproduce the build locally

Before guessing, run what the platform runs, in a clean state:

Terminal
rm -rf node_modules dist
npm ci          # uses the lockfile exactly, like CI
npm run build

npm ci is important: it installs exactly what the lockfile says and fails if package.json and the lockfile disagree, which is precisely how the platform behaves. Use the same Node version as the platform (see Node versions).

Rollbacks: moving the pointer

If production breaks, do not debug under pressure. Restore the last good deploy first, then investigate.

  • Vercel: Instant Rollback. In the project's Deployments list, open the menu on an earlier production deployment and choose Instant Rollback, or run vercel rollback. Your domains are re-pointed to that deployment immediately, without rebuilding. The CLI also has vercel promote <url> to make any chosen deployment the production one. Note that after a rollback, automatic assignment of new deployments to production may pause until you promote or deploy again, so read the dashboard banner.
  • Netlify: publish an older deploy. Open Deploys, click the older successful deploy and choose Publish deploy. Netlify then locks publishing to that deploy, so new builds are created but are not published until you click Start auto publishing. This is deliberate: it prevents a new push from instantly overwriting your rollback.

Because the old deploy is a stored, complete snapshot, nothing is rebuilt, so recovery takes seconds. One caution: a rollback restores files and functions but not your database. If a deploy also changed your data structure, plan a compatible fix.

Node.js Rollback pointer (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Deploy hooks

Sometimes you want to rebuild without a commit: the content in your CMS changed, or a nightly refresh. Both platforms offer deploy hooks (Vercel) or build hooks (Netlify): a secret URL. Sending an HTTP POST to it triggers a build of the chosen branch. Create one in the dashboard under the project's Git or Build settings.

Terminal
curl -X POST "https://api.example-platform.test/hooks/SECRET-ID"

(The URL above is a placeholder; copy the real one from your dashboard.) Treat hook URLs like passwords: anyone who has one can trigger builds and use your build minutes. Revoke and recreate a hook if it leaks.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why is a rollback so fast?

    Older deploys are complete snapshots, so nothing needs to be rebuilt.
  2. 2. On Netlify, why does publishing an older deploy lock auto publishing?

    The lock keeps the chosen deploy live until you resume auto publishing.
  3. 3. Which npm command best reproduces the platform's dependency install?

    npm ci installs exactly from the lockfile, like the platform's clean build.
  4. 4. What is a deploy or build hook?

    Hooks let external systems, such as a CMS, trigger builds.

Summary

  • A build runs in phases: clone, restore cache, install, build, upload, finish. Read the log from the failing line upward.
  • Most failures come from missing dependencies, file-name case, Node version differences or missing variables.
  • Reproduce locally with a clean install using npm ci.
  • Rollback re-points live traffic to an older immutable deploy; Netlify also locks auto publishing.
  • Deploy hooks rebuild on demand; keep their URLs secret.

Next: Monorepos and Ignored Builds