Skip to content
SlashClone
DiscoverUse in ClaudeSubmit a link
Sign in
Made by@shipcheck

Deploy doctor

@shipcheck/deploy-doctor

Paste a failed Vercel or Netlify build log and get the most likely cause and a fix you can apply. Recognizes about twenty common failures: letter-case import errors, missing packages, missing env vars, prerender errors, window is not defined, lockfile drift, peer dependency conflicts, wrong Node version, out of memory, wrong output or root folder, oversized functions, and more.

SkillDevOpsv1.0.0 (latest)Tested
Use in Claude Save Like Clone Comment
Activity
New: be the first to try it
  1. 1---
  2. 2name: deploy-doctor
  3. 3description: Triage a failed Vercel or Netlify deploy from its build log. Finds the first real error, names the most likely cause (letter-case imports, missing packages, missing env vars, prerender errors, window is not defined, useSearchParams Suspense, lockfile drift, ERESOLVE peer deps, wrong Node version, out of memory, wrong output or root folder, oversized functions, Prisma generate), and walks through the fix. Use when the user pastes a build log, says "my deploy failed", "works locally but not on Vercel", "Netlify build failed", or "Command npm run build exited with 1".
  4. 4license: MIT
  5. 5---
  6. 6
  7. 7# Deploy doctor
  8. 8
  9. 9"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.
  10. 10
  11. 11## Inputs
  12. 12
  13. 13- **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.
  14. 14- Which host (Vercel or Netlify) and whether it failed on Production or a Preview, if the log does not say.
  15. 15
  16. 16## Steps
  17. 17
  18. 181. **Save and triage.**
  19. 19
  20. 20 ```bash
  21. 21 node scripts/triage-log.mjs data/build-log.txt --json out/deploy-triage.json --md out/deploy-triage.md
  22. 22 ```
  23. 23
  24. 242. **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.
  25. 253. **Confirm against the project** before suggesting anything. Examples:
  26. 26 - Letter-case import: list the real file name in that folder and compare it letter by letter.
  27. 27 - Missing package: check `package.json` dependencies for it.
  28. 28 - Missing env var: search the code for where it is read, and check whether that happens at import time.
  29. 29 - Node version: read `engines` in `package.json` and `.nvmrc`.
  30. 30 - Output folder: read `vercel.json`, `netlify.toml`, and the framework config.
  31. 314. **Explain in two or three plain sentences:** what broke, why it works locally, and the fix.
  32. 325. **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.
  33. 336. **Verify locally when you can.** Offer to run the production build, which reproduces most of these failures:
  34. 34
  35. 35 ```bash
  36. 36 npm run build
  37. 37 ```
  38. 38
  39. 39 Use `pnpm run build` or `yarn build` to match the project's lockfile. Then the user redeploys.
  40. 40
  41. 417. **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.
  42. 42
  43. 43## Output format
  44. 44
  45. 45```markdown
  46. 46# Deploy fix: <host>, <framework>
  47. 47**Cause:** NEXT_PUBLIC_SUPABASE_URL is not set on Vercel, so /pricing fails while prerendering.
  48. 48**Why it worked locally:** your .env.local has it; Vercel never sees that file.
  49. 49
  50. 50## Fix
  51. 511. Vercel, Project Settings, Environment Variables: add NEXT_PUBLIC_SUPABASE_URL for Production and Preview.
  52. 522. Redeploy (env vars with NEXT_PUBLIC_ are baked in at build time).
  53. 53
  54. 54## Also in the log (knock-on, fixed by the above)
  55. 55- Error occurred prerendering page "/pricing"
  56. 56```
  57. 57
  58. 58## Guardrails
  59. 59
  60. 60- Logs can contain secrets. The script masks long tokens in its report; never repeat a key from the log in chat.
  61. 61- 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.
  62. 62- Never move a server secret to a `NEXT_PUBLIC_` or `VITE_` name to make a build pass.
  63. 63- Never deploy, redeploy, or change host settings yourself. The user does that.
Sign in to comment on a line