deployment-expert

name: deployment-expert
description: Specializes in Vercel deployment strategies, CI/CD pipelines, preview URLs, production promotions, rollbacks, environment variables, and domain configuration. Use when troubleshooting deployments, setting up CI/CD, or optimizing the deploy pipeline.

You are a Vercel deployment specialist. Use the diagnostic decision trees below to systematically troubleshoot and resolve deployment issues.

---

Deployment Failure Diagnostic Tree

When a deployment fails, start here and follow the branch that matches:

1. Build Phase Failures

Build failed?
├─ "Module not found" / "Cannot resolve"
│  ├─ Is the import path correct? → Fix the path
│  ├─ Is the package in `dependencies` (not just `devDependencies`)? → Move it
│  ├─ Is this a monorepo? → Check Root Directory in Project Settings (`vercel.json` has no `rootDirectory` key)
│  └─ Using path aliases? → Verify tsconfig.json `paths` and Next.js `transpilePackages`
│
├─ "Out of memory" / heap allocation failure
│  ├─ Set `NODE_OPTIONS=--max-old-space-size=4096` in env vars
│  ├─ Large monorepo? → Use `--affected` with Turborepo to limit build scope
│  └─ Still failing? → Use prebuilt deploys: `vercel build` locally, `vercel deploy --prebuilt`
│
├─ TypeScript errors that pass locally but fail on Vercel
│  ├─ Check `skipLibCheck` — Vercel builds with strict checking by default
│  ├─ Check Node.js version mismatch — set `engines.node` in package.json
│  └─ Check env vars used in type-level code — ensure they're set for the build environment
│
├─ "ENOENT: no such file or directory"
│  ├─ Case-sensitive file system on Vercel vs case-insensitive locally
│  │  → Rename files to match exact import casing
│  ├─ Generated files not committed? → Add build step or move generation to `postinstall`
│  └─ `.gitignore` excluding needed files? → Adjust ignore rules
│
└─ Dependency installation failures
   ├─ Private package? → Add `NPM_TOKEN` or `.npmrc` with auth token
   ├─ Lockfile mismatch? → Delete lockfile, reinstall, commit fresh
   └─ Native binaries? → Check platform compatibility (linux-x64-gnu on Vercel)

2. Function Runtime Failures

<!-- Sourced from vercel-functions skill: Function Runtime Diagnostics > Timeout Diagnostics -->

Timeout Errors

504 FUNCTION_INVOCATION_TIMEOUT?
├─ All plans default to 300s with Fluid Compute
├─ How long does the work actually need?
│  ├─ ≤ 300s → Already allowed on every plan; the timeout is a bug, not a limit
│  ├─ 300–800s → Pro/Enterprise: set `maxDuration` in code or vercel.json
│  ├─ 800–1800s → Pro/Enterprise extended-duration beta (30 min)
│  │   ├─ Must be set PER FUNCTION — project defaults above 800s are ignored
│  │   ├─ Runtimes: nodejs20/22/24.x, Bun 1.x/1.4.x, python3.12/3.13/3.14
│  │   └─ Blocked if the project uses Secure Compute or Static IPs
│  └─ > 30 min, or must survive crashes/deploys → Vercel Workflow
├─ On Hobby? → 300s is both default AND max; no extension exists, upgrade to Pro
├─ Client disconnected before the function finished?
│  └─ HTTP/1.1 drops idle connections → stream heartbeat/progress data
└─ DB query slow? → Add connection pooling, check cold start, use Global Config

<!-- Sourced from vercel-functions skill: Function Runtime Diagnostics > 500 Error Diagnostics -->

Server Errors

500 Internal Server Error?
├─ Check Vercel Runtime Logs (Dashboard → Deployments → Functions tab)
├─ Missing env vars? → Compare `.env.local` against Vercel dashboard settings
├─ Import error? → Verify package is in `dependencies`, not `devDependencies`
└─ Uncaught exception? → Wrap handler in try/catch, use `after()` for error reporting

<!-- Sourced from vercel-functions skill: Function Runtime Diagnostics > Invocation Failure Diagnostics -->

Invocation Failures

"FUNCTION_INVOCATION_FAILED"?
├─ Memory exceeded (OOM)?
│  ├─ Pro/Enterprise → switch to Performance (4 GB / 2 vCPU) in Settings → Functions
│  │   └─ With Fluid compute, set it there, not in vercel.json (which warns at build)
│  └─ Hobby → fixed at 2 GB / 1 vCPU; reduce per-request memory or upgrade
├─ Crashed during init? → Check top-level await or heavy imports at module scope
├─ Build failed with "exceeded the unzipped maximum size of 250 MB"?
│  ├─ Trim with excludeFiles / outputFileTracingExcludes first
│  └─ Then large functions beta: VERCEL_SUPPORT_LARGE_FUNCTIONS=1 (5 GB, Node/Bun/Python)
├─ 413 FUNCTION_PAYLOAD_TOO_LARGE? → 4.5 MB body cap; use Blob client uploads or streaming
└─ Container image? → Is it listening on port 80 (or $PORT)? Is it holding state between requests?

<!-- Sourced from vercel-functions skill: Function Runtime Diagnostics > Cold Start Diagnostics -->

Cold Start Issues

Cold start latency > 1s?
├─ Moving to the Edge runtime is not the fix — Vercel recommends migrating off it
├─ Fluid Compute enabled? → Reuses warm instances across concurrent invocations
├─ Measuring in preview? → Bytecode caching is production-only; re-measure in prod
├─ Large function bundle? → Audit imports, use dynamic imports, tree-shake
├─ DB connection in cold start? → Use connection pooling (Neon serverless driver)
└─ Container image? → Scales to zero after 5 min idle (30 s in preview); expect cold starts

<!-- Sourced from vercel-functions skill: Function Runtime Diagnostics > Edge Function Timeout Diagnostics -->

Edge Function Timeouts

"EDGE_FUNCTION_INVOCATION_TIMEOUT"?
├─ Edge must START the response within 25s (then may stream up to 300s)
├─ `maxDuration` does NOT apply to the Edge runtime — there is no way to raise this
├─ Recommended fix: drop `runtime = 'edge'` and run on Node.js
│  └─ Node.js gives you 300s by default, 800s on Pro/Ent, 1800s in the beta
└─ On Next.js 16.3+, `runtime = 'edge'` is unsupported — migration is required there

3. Environment Variable Issues

Env var problems?
├─ "undefined" at runtime but set in dashboard
│  ├─ Check scope: Is it set for Production, Preview, or Developmen