Deploy doctor

Deploy doctor

"It builds on my machine" usually means one of about twenty things. This skill reads the build log, finds the first real error (later errors are mostly knock-on effects), matches it to a known cause, and checks the project to confirm before suggesting a fix.

Inputs

• The build log. Ask the user to open the failed deploy, copy the whole build log, and paste it. Save it to data/build-log.txt. If they only paste the last few lines, ask for about 50 lines above the first red error too.
• Which host (Vercel or Netlify) and whether it failed on Production or a Preview, if the log does not say.

Steps

1. Save and triage.

   node scripts/triage-log.mjs data/build-log.txt --json out/deploy-triage.json --md out/deploy-triage.md

2. Read the result and the log lines around first_error. The "Most likely cause" is the earliest known pattern. If the first error line comes before it and looks unrelated, trust the first error and say so.

3. Confirm against the project before suggesting anything. Examples:

   • Letter-case import: list the real file name in that folder and compare it letter by letter.
   • Missing package: check package.json dependencies for it.
   • Missing env var: search the code for where it is read, and check whether that happens at import time.
   • Node version: read engines in package.json and .nvmrc.
   • Output folder: read vercel.json, netlify.toml, and the framework config.
4. Explain in two or three plain sentences: what broke, why it works locally, and the fix.
5. Fix. Show the exact change (a diff, a renamed file, or the setting to change in the host dashboard) and apply code changes only after the user says yes. Host settings (env vars, Node version, root directory) are changed by the user in the dashboard; tell them exactly where.

6. Verify locally when you can. Offer to run the production build, which reproduces most of these failures:

   npm run build

   Use pnpm run build or yarn build to match the project's lockfile. Then the user redeploys.

7. If nothing matched, read the log yourself from the top, find the first error, and reason it through. Add what you learned to the report.

Output format

# Deploy fix: <host>, <framework>
**Cause:** NEXT_PUBLIC_SUPABASE_URL is not set on Vercel, so /pricing fails while prerendering.
**Why it worked locally:** your .env.local has it; Vercel never sees that file.

## Fix
1. Vercel, Project Settings, Environment Variables: add NEXT_PUBLIC_SUPABASE_URL for Production and Preview.
2. Redeploy (env vars with NEXT_PUBLIC_ are baked in at build time).

## Also in the log (knock-on, fixed by the above)
- Error occurred prerendering page "/pricing"

Guardrails

• Logs can contain secrets. The script masks long tokens in its report; never repeat a key from the log in chat.
• Never "fix" a build by turning off checks (ignoreBuildErrors, eslint.ignoreDuringBuilds, --force, deleting the lockfile) unless the user asks for a stopgap, and then label it as one.
• Never move a server secret to a NEXT_PUBLIC_ or VITE_ name to make a build pass.
• Never deploy, redeploy, or change host settings yourself. The user does that.

Deploy doctor

Paste a failed Vercel or Netlify build log and get the most likely cause, why it worked on your machine, and the exact fix. It knows about twenty of the most common reasons builds fail, and Claude checks your project to confirm before changing anything.

For: anyone whose app runs fine locally but fails to deploy. No DevOps background needed.

Example

Input: a Vercel log that ends in Error occurred prerendering page "/pricing" after Error: supabaseUrl is required.

Output (out/deploy-triage.md):

Platform: Vercel | Framework: Next.js | Package manager: npm

## Most likely cause: Environment variable missing at build time
Line 18: Error: supabaseUrl is required.
A required environment variable is not set for this build. Values in your
local .env file are not uploaded to the host.

Fix:
1. Add the variable in the host's project settings, under Environment
   Variables, for the environment that failed (Production or Preview).
2. Variables with NEXT_PUBLIC_ or VITE_ prefixes are baked in at build
   time, so redeploy after adding them.

## Also seen: A page failed while being prerendered

Try it on the bundled logs: node scripts/triage-log.mjs examples/vercel-nextjs-env.txt or examples/netlify-vite-case.txt.

What it recognizes

Letter-case imports, missing packages, Node modules on the edge, missing env vars, prerender errors, window is not defined, useSearchParams without Suspense, dynamic server usage, TypeScript and lint errors, lockfile drift, ERESOLVE peer conflicts, wrong Node version, out of memory, missing build script, command not found, wrong output or root folder, oversized functions, Prisma client not generated, and private package auth.

What it can access

• Reads the log you save to data/, plus package.json, host config (vercel.json, netlify.toml), framework config, and your source folders to confirm the cause.
• Writes the triage report to out/.
• Can run your production build locally (npm run build, pnpm run build, or yarn build) to reproduce the error.
• No network, no env vars. It never deploys or changes host settings.

Setup

None. Needs Node 22 or later.