Deploy & Ops

Vercel Deploy Debugging

Diagnose the common ways a Next.js build passes locally but fails on Vercel: pnpm build gates, type errors, env vars, and uncommitted files.

verceldeploynextjscipnpm

1 file

Description

Diagnose the common ways a Next.js build passes locally but fails on Vercel: pnpm build gates, type errors, env vars, and uncommitted files.

Install

SKILL.md

name: vercel-deploy-debugging description: Use when a Vercel deployment fails but the app builds locally, or when a push to the production branch does not produce the expected running revision. Covers pnpm install gates, type gates, env vars, and commit hygiene.

Vercel Deploy Debugging

When to trigger

A red deploy on Vercel, a build that works with pnpm build locally but fails in CI, or production serving an older commit than you pushed.

Diagnosis order

Read the build log top to bottom. The first error is the real one; later errors are usually cascades.
Reproduce CI conditions locally: CI=1 pnpm install --frozen-lockfile. This surfaces lockfile drift and blocked dependency build scripts that a normal pnpm install hides.
Reproduce the type gate exactly as the deploy runs it. If the project gates on tsc --noEmit or the native preview, run that same command, not just next build.
Verify the committed tree, not the working tree. Agents leave unstaged files; a commit that imports an unstaged module passes locally and fails CI. Check with a temp worktree of HEAD:
```
git worktree add /tmp/verify HEAD && cd /tmp/verify && pnpm install && pnpm build
```

Common causes

pnpm 11 blocks dependency build scripts by default and hard-fails with ERR_PNPM_IGNORED_BUILDS. The approval list is allowBuilds: in pnpm-workspace.yaml. The pnpm 10 onlyBuiltDependencies and pnpm 9 package.json#pnpm keys are silently ignored by pnpm 11.
A missing env var that exists in .env.local but was never added to the Vercel project. Server code that reads it at build time fails the build; code that reads it at request time fails at runtime.
Two concurrent builds racing on .next produce ENOENT on build manifest temp files. Never run two builds in the same checkout at once.

Pitfalls

next build succeeding does not mean the type gate passes. If the deploy runs a separate typecheck, an untyped file can still break it.
Production can keep serving the last good deploy after a failed one. A green URL is not proof your commit shipped. Verify the served commit hash against git rev-parse origin/main.

Added 2026-07-01. Back to the Skill Library.

Get Smarter About AI Dev

New tutorials, open-source projects, and deep dives on coding agents - delivered weekly.

One email per weekReal code, not theoryFree forever

Diagnosis order

Read the build log top to bottom. The first error is the real one; later errors are usually cascades.

Reproduce CI conditions locally: CI=1 pnpm install --frozen-lockfile. This surfaces lockfile drift and blocked dependency build scripts that a normal pnpm install hides.

Reproduce the type gate exactly as the deploy runs it. If the project gates on tsc --noEmit or the native preview, run that same command, not just next build.

Verify the committed tree, not the working tree. Agents leave unstaged files; a commit that imports an unstaged module passes locally and fails CI. Check with a temp worktree of HEAD:

git worktree add /tmp/verify HEAD && cd /tmp/verify && pnpm install && pnpm build

Common causes

pnpm 11 blocks dependency build scripts by default and hard-fails with ERR_PNPM_IGNORED_BUILDS. The approval list is allowBuilds: in pnpm-workspace.yaml. The pnpm 10 onlyBuiltDependencies and pnpm 9 package.json#pnpm keys are silently ignored by pnpm 11.

A missing env var that exists in .env.local but was never added to the Vercel project. Server code that reads it at build time fails the build; code that reads it at request time fails at runtime.

Two concurrent builds racing on .next produce ENOENT on build manifest temp files. Never run two builds in the same checkout at once.

Pitfalls

next build succeeding does not mean the type gate passes. If the deploy runs a separate typecheck, an untyped file can still break it.

Production can keep serving the last good deploy after a failed one. A green URL is not proof your commit shipped. Verify the served commit hash against git rev-parse origin/main.