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#!/usr/bin/env node
  2. 2// Triage a failed Vercel or Netlify build log.
  3. 3// Detects platform, framework, package manager and Node version, then matches known
  4. 4// failure signatures and ranks them by where they appear (the first real error is
  5. 5// usually the cause; later errors are often knock-on effects).
  6. 6// Node built-ins only. Reads a file or stdin; never calls any host API.
  7. 7//
  8. 8// Usage: node scripts/triage-log.mjs [data/build-log.txt | -] [--json out/deploy-triage.json] [--md out/deploy-triage.md]
  9. 9
  10. 10import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
  11. 11import { dirname } from "node:path";
  12. 12
  13. 13function parseArgs(argv) {
  14. 14 const args = { input: "data/build-log.txt", json: null, md: null };
  15. 15 const rest = [];
  16. 16 for (let i = 0; i < argv.length; i++) {
  17. 17 const a = argv[i];
  18. 18 if (a === "--json") args.json = argv[++i];
  19. 19 else if (a === "--md") args.md = argv[++i];
  20. 20 else if (a === "-h" || a === "--help") {
  21. 21 console.log("Usage: node scripts/triage-log.mjs [log-file | -] [--json file] [--md file]");
  22. 22 process.exit(0);
  23. 23 } else rest.push(a);
  24. 24 }
  25. 25 if (rest[0]) args.input = rest[0];
  26. 26 return args;
  27. 27}
  28. 28
  29. 29// Each signature: id, title, patterns (first match wins), cause, fix (steps). `{1}` in text is the
  30. 30// first capture; `[? ... ?]` is kept only when there is a capture.
  31. 31const SIGNATURES = [
  32. 32 {
  33. 33 id: "missing-module-local",
  34. 34 title: "Import path not found (often letter case)",
  35. 35 patterns: [/Module not found: (?:Error: )?Can't resolve '((?:\.{1,2}\/|@\/|~\/|src\/)[^']+)'/, /Failed to resolve import "((?:\.{1,2}\/|@\/|~\/)[^"]+)"/, /Cannot find module '((?:\.{1,2}\/|@\/)[^']+)'/],
  36. 36 cause: "The file '{1}' cannot be found on the build server. Builds run on Linux, where 'Button.tsx' and 'button.tsx' are different files, while your Mac treats them as the same.",
  37. 37 fix: [
  38. 38 "Check the exact spelling and letter case of '{1}' against the file on disk.",
  39. 39 "If only the case differs, rename through git so it sees the change: git mv src/components/button.tsx src/components/Button.tsx (via a temp name if needed).",
  40. 40 "If the file is in .gitignore or was never committed, commit it.",
  41. 41 ],
  42. 42 },
  43. 43 {
  44. 44 id: "missing-module-package",
  45. 45 title: "Package not installed",
  46. 46 patterns: [
  47. 47 /Module not found: (?:Error: )?Can't resolve '((?!\.|@\/|~\/|src\/)[^']+)'/,
  48. 48 /Cannot find module '((?!\.|@\/)[^']+)'/,
  49. 49 /Failed to resolve import "((?!\.|@\/|~\/)[^"]+)"/,
  50. 50 /Cannot find package '([^']+)'/,
  51. 51 ],
  52. 52 cause: "'{1}' is imported but not installed on the build server. Usually it is missing from package.json, or only installed globally on your machine.",
  53. 53 fix: [
  54. 54 "Add it to dependencies (not devDependencies if it is used at runtime) and commit package.json and the lockfile.",
  55. 55 "If it is a Node built-in like fs or path, that code is being bundled for the browser or edge. Move it to server-only code.",
  56. 56 ],
  57. 57 },
  58. 58 {
  59. 59 id: "edge-node-module",
  60. 60 title: "Node API used in the edge runtime",
  61. 61 patterns: [/edge runtime does not support Node\.js '([^']+)' module/i, /A Node\.js (?:API|module) is used \(([^)]+)\) which is not supported in the Edge Runtime/],
  62. 62 cause: "Code running on the edge (middleware or a route with runtime = 'edge') uses the Node module '{1}', which the edge does not have.",
  63. 63 fix: ["Remove export const runtime = 'edge' from that route, or swap the library for an edge-compatible one.", "Keep middleware small: no database drivers or Node SDKs in middleware."],
  64. 64 },
  65. 65 {
  66. 66 id: "missing-env",
  67. 67 title: "Environment variable missing at build time",
  68. 68 patterns: [
  69. 69 /Environment variable not found: ([A-Z0-9_]+)/,
  70. 70 /Missing (?:required )?environment variable[s]?:? ?["'`]?([A-Z0-9_]+)?/i,
  71. 71 /(supabaseUrl|supabaseKey) is required/,
  72. 72 /The ([A-Z0-9_]+) environment variable is missing/,
  73. 73 /Neither apiKey nor config\.authenticator provided/,
  74. 74 /Invalid environment variables/,
  75. 75 /env(?:ironment)? variable ["'`]?([A-Z0-9_]{3,})["'`]? (?:is )?(?:not set|undefined|missing)/i,
  76. 76 ],
  77. 77 cause: "A required environment variable is not set for this build[? (the log names '{1}')?]. Values in your local .env file are not uploaded to the host.",
  78. 78 fix: [
  79. 79 "Add the variable in the host's project settings, under Environment Variables, for the environment that failed (Production or Preview).",
  80. 80 "Variables with NEXT_PUBLIC_ or VITE_ prefixes are baked in at build time, so redeploy after adding them.",
  81. 81 "If the code reads it at import time (top of a file), it also runs during build. Move the read inside the function that needs it.",
  82. 82 ],
  83. 83 },
  84. 84 {
  85. 85 id: "prerender-error",
  86. 86 title: "A page failed while being prerendered",
  87. 87 patterns: [/Error occurred prerendering page "([^"]+)"/],
  88. 88 cause: "Next.js renders '{1}' at build time and it threw. Usually a fetch to your own API (not running during build), a missing env var, or data that is undefined at build time.",
  89. 89 fix: [
  90. 90 "Read the error just above this line in the log; it names the real cause.",
  91. 91 "Do not fetch your own /api routes from server components. Call the function directly.",
  92. 92 "If the page needs request-time data, mark it dynamic: export const dynamic = 'force-dynamic'.",
  93. 93 ],
  94. 94 },
  95. 95 {
  96. 96 id: "browser-global-on-server",
  97. 97 title: "Browser-only code ran on the server",
  98. 98 patterns: [/ReferenceError: (window|document|localStorage|navigator|self) is not defined/],
  99. 99 cause: "'{1}' only exists in the browser, but this code ran during server rendering or the build.",
  100. 100 fix: ["Add 'use client' to the component and touch '{1}' only inside useEffect.", "For a library that needs the browser, load it with next/dynamic and ssr: false."],
  101. 101 },
  102. 102 {
  103. 103 id: "use-search-params-suspense",
  104. 104 title: "useSearchParams needs a Suspense boundary",
  105. 105 patterns: [/useSearchParams\(\) should be wrapped in a suspense boundary(?: at page "([^"]+)")?/i],
  106. 106 cause: "A client component reads search params on a page that Next.js tries to render statically.",
  107. 107 fix: ["Wrap the component that calls useSearchParams in <Suspense fallback={null}>.", "Or read searchParams in the page (server) and pass them down as props."],
  108. 108 },
  109. 109 {
  110. 110 id: "dynamic-server-usage",
  111. 111 title: "Static page uses request data",
  112. 112 patterns: [/Dynamic server usage: ?([^\n]*)/, /couldn't be rendered statically because it used ([^\n]+)/],
  113. 113 cause: "A page Next.js wanted to build statically reads cookies, headers or search params ({1}).",
  114. 114 fix: ["Add export const dynamic = 'force-dynamic' to that page or route, or move the request-time read out of it."],
  115. 115 },
  116. 116 {
  117. 117 id: "type-error",
  118. 118 title: "TypeScript error fails the build",
  119. 119 patterns: [/Type error: ([^\n]+)/, /error TS\d+: ([^\n]+)/],
  120. 120 cause: "The production build type-checks your code and found: {1}",
  121. 121 fix: [
  122. 122 "Run the build locally (npm run build) to see the same error with the file and line.",
  123. 123 "Fix the type rather than setting typescript.ignoreBuildErrors; that flag hides real bugs.",
  124. 124 ],
  125. 125 },
  126. 126 {
  127. 127 id: "lint-error",
  128. 128 title: "Lint errors fail the build",
  129. 129 patterns: [/(?:ESLint|eslint).{0,40}(?:error|Error)[^\n]*/, /Error: +[^\n]*\s(react\/[a-z-]+|@typescript-eslint\/[a-z-]+|react-hooks\/[a-z-]+)/],
  130. 130 cause: "The build runs the linter and treats errors as failures.",
  131. 131 fix: ["Run npm run lint locally and fix the listed lines.", "Common one: react/no-unescaped-entities. Write &apos; instead of a raw apostrophe in JSX text."],
  132. 132 },
  133. 133 {
  134. 134 id: "lockfile-out-of-sync",
  135. 135 title: "Lockfile does not match package.json",
  136. 136 patterns: [
  137. 137 /`npm ci` can only install packages when your package\.json and package-lock\.json[^\n]* are in sync/,
  138. 138 /ERR_PNPM_OUTDATED_LOCKFILE/,
  139. 139 /Your lockfile needs to be updated, but yarn was run with `--frozen-lockfile`/,
  140. 140 /lockfile had changes, but lockfile is frozen/,
  141. 141 /ERR_PNPM_LOCKFILE_CONFIG_MISMATCH/,
  142. 142 ],
  143. 143 cause: "package.json changed but the lockfile was not updated and committed, or two lockfiles (npm and pnpm, say) disagree.",
  144. 144 fix: [
  145. 145 "Run your package manager's install locally (npm install, pnpm install, or yarn) and commit the updated lockfile.",
  146. 146 "Keep exactly one lockfile. Delete the others so the host picks the right package manager.",
  147. 147 ],
  148. 148 },
  149. 149 {
  150. 150 id: "peer-deps",
  151. 151 title: "npm peer dependency conflict",
  152. 152 patterns: [/ERESOLVE (?:unable to resolve dependency tree|could not resolve)/],
  153. 153 cause: "Two packages want incompatible versions of a shared dependency (often React).",
  154. 154 fix: [
  155. 155 "Read the 'Could not resolve dependency' lines to see which package needs which version, and upgrade that package.",
  156. 156 "As a stopgap, add legacy-peer-deps=true to an .npmrc in the repo. Treat it as a temporary fix.",
  157. 157 ],
  158. 158 },
  159. 159 {
  160. 160 id: "node-version",
  161. 161 title: "Wrong Node.js version",
  162. 162 patterns: [/The engine "node" is incompatible with this module\. Expected version "([^"]+)"/, /requires (?:a )?Node(?:\.js)? (?:version )?([>=^~\d.x ]+)/i, /Node\.js version ([\d.]+) (?:has reached End-of-Life|is not supported|is deprecated)/i, /You are using Node\.js ([\d.]+)/],
  163. 163 cause: "The build server uses a Node version that a package or the framework does not support ({1}).",
  164. 164 fix: [
  165. 165 "Vercel: Project Settings, General, Node.js Version. Netlify: set NODE_VERSION in environment variables or add an .nvmrc file.",
  166. 166 "Also set \"engines\": { \"node\": \"22.x\" } in package.json so local and host agree.",
  167. 167 ],
  168. 168 },
  169. 169 {
  170. 170 id: "out-of-memory",
  171. 171 title: "Build ran out of memory",
  172. 172 patterns: [/JavaScript heap out of memory/, /Reached heap limit/, /exited with (?:code )?137/, /\bSIGKILL\b/],
  173. 173 cause: "The build used more memory than the build machine has.",
  174. 174 fix: [
  175. 175 "Set NODE_OPTIONS=--max-old-space-size=4096 in the build environment variables.",
  176. 176 "Look for huge imports (whole icon packs, big JSON files) and turn off production source maps if you do not use them.",
  177. 177 ],
  178. 178 },
  179. 179 {
  180. 180 id: "missing-build-script",
  181. 181 title: "No build script",
  182. 182 patterns: [/Missing script: "?build"?/i, /missing script: build/i],
  183. 183 cause: "The host runs the build command but package.json has no matching script.",
  184. 184 fix: ["Add \"build\" to scripts in package.json, or change the build command in the host settings to the one you use locally."],
  185. 185 },
  186. 186 {
  187. 187 id: "command-not-found",
  188. 188 title: "Build command not found",
  189. 189 patterns: [/(?:sh|bash): (?:line \d+: )?([\w.-]+): (?:command )?not found/, /exit(?:ed with)? code:? 127/i],
  190. 190 cause: "The build calls a command[? ('{1}')?] that is not installed on the build server.",
  191. 191 fix: ["If it is a package CLI, add the package to devDependencies so it lands in node_modules/.bin.", "Check the build command in the host settings for typos."],
  192. 192 },
  193. 193 {
  194. 194 id: "output-dir",
  195. 195 title: "Output folder not found",
  196. 196 patterns: [/No Output Directory named "([^"]+)" found/, /Deploy directory '([^']+)' does not exist/, /publish directory[^\n]*'([^']+)'[^\n]*does not exist/i],
  197. 197 cause: "The build finished but the folder the host deploys ('{1}') does not exist.",
  198. 198 fix: [
  199. 199 "Set the output or publish directory to what your framework writes: Next.js on Vercel needs none (framework preset), Vite uses dist, Create React App uses build, Astro uses dist.",
  200. 200 "On Netlify with Next.js, use the Next.js runtime rather than a publish folder.",
  201. 201 ],
  202. 202 },
  203. 203 {
  204. 204 id: "root-directory",
  205. 205 title: "Wrong root or base directory",
  206. 206 patterns: [/The specified Root Directory "([^"]+)" does not exist/, /Base directory does not exist: ?([^\n]*)/, /ENOENT: no such file or directory, open '([^']*package\.json)'/, /Could not read package\.json/],
  207. 207 cause: "The host looks for your app in the wrong folder ({1}). Common in monorepos or when the app lives in a subfolder.",
  208. 208 fix: ["Set Root Directory (Vercel) or Base directory (Netlify) to the folder that holds package.json."],
  209. 209 },
  210. 210 {
  211. 211 id: "function-too-large",
  212. 212 title: "Serverless function too large",
  213. 213 patterns: [/exceeds? the (?:maximum|unzipped maximum) size/i, /Serverless Function[^\n]*exceeded[^\n]*size/i, /function[^\n]*is too large/i],
  214. 214 cause: "A server function bundles too much, often a big dependency (headless browser, ML library) or files pulled in by a wide import.",
  215. 215 fix: ["Find the heavy dependency in the log and load it only where needed, or move that job to a separate service.", "Exclude large folders from the function trace (Next.js: outputFileTracingExcludes)."],
  216. 216 },
  217. 217 {
  218. 218 id: "prisma-client",
  219. 219 title: "Prisma client not generated",
  220. 220 patterns: [/@prisma\/client did not initialize yet/, /Prisma Client could not locate the Query Engine/, /Prisma has detected that this project was built on Vercel/],
  221. 221 cause: "The build uses a cached node_modules, so prisma generate never ran.",
  222. 222 fix: ["Add \"postinstall\": \"prisma generate\" to package.json scripts, or put prisma generate before the build command."],
  223. 223 },
  224. 224 {
  225. 225 id: "private-package",
  226. 226 title: "Private package or registry auth failed",
  227. 227 patterns: [/npm ERR! code E401/, /\b401 Unauthorized\b[^\n]*registry/i, /npm ERR! 404 Not Found - GET (\S+)/],
  228. 228 cause: "The build cannot download a package[? ({1})?]: it is private, misspelled, or needs a registry token.",
  229. 229 fix: ["Check the package name. For private packages, add the registry token as an env var on the host and reference it from .npmrc, never paste the token itself into .npmrc."],
  230. 230 },
  231. 231];
  232. 232
  233. 233const GENERIC_ERROR = /\b(?:Error|ERROR|error|Failed|FAILED|failed)\b/;
  234. 234const NOISE = /(?:npm WARN|warning|deprecated|Retrying|Cloning|Restored build cache|Downloading|Installing)/i;
  235. 235
  236. 236function detect(log) {
  237. 237 const platform = /Netlify Build|netlify\.toml|Netlify CLI|@netlify\//i.test(log)
  238. 238 ? "Netlify"
  239. 239 : /Vercel CLI|Running build in|vercel\.json|Build Completed in \/vercel|Deploying outputs/i.test(log)
  240. 240 ? "Vercel"
  241. 241 : "unknown";
  242. 242 const framework =
  243. 243 [
  244. 244 ["Next.js", /▲ Next\.js|next build|Next\.js \d/],
  245. 245 ["Vite", /vite v\d|vite build/],
  246. 246 ["Astro", /astro build|\bastro v?\d/i],
  247. 247 ["SvelteKit", /@sveltejs\/kit|svelte-kit/],
  248. 248 ["Nuxt", /nuxi build|Nuxt \d/],
  249. 249 ["Remix", /remix build|@remix-run/],
  250. 250 ["Create React App", /react-scripts build/],
  251. 251 ].find(([, re]) => re.test(log))?.[0] ?? "unknown";
  252. 252 const pm =
  253. 253 /pnpm install|ERR_PNPM|pnpm-lock/.test(log) ? "pnpm" : /yarn install|yarn\.lock|\byarn run\b/.test(log) ? "yarn" : /bun install|bun\.lockb?/.test(log) ? "bun" : /npm (?:ci|install|run)|npm ERR!|package-lock/.test(log) ? "npm" : "unknown";
  254. 254 const node = /(?:Node(?:\.js)? (?:version )?|node v)(\d+\.\d+(?:\.\d+)?)/i.exec(log)?.[1] ?? null;
  255. 255 return { platform, framework, package_manager: pm, node };
  256. 256}
  257. 257
  258. 258function fill(text, capture) {
  259. 259 return text
  260. 260 .replace(/\[\?([^?]*)\?\]/g, (_, inner) => (capture ? inner.replace("{1}", capture) : ""))
  261. 261 .replace(/\{1\}/g, capture ?? "?");
  262. 262}
  263. 263
  264. 264// Mask long token-like strings so pasted logs do not carry secrets into reports.
  265. 265function mask(line) {
  266. 266 return line.replace(/[A-Za-z0-9_\-+=]{32,}/g, (m) => `${m.slice(0, 4)}...[masked ${m.length}]`);
  267. 267}
  268. 268
  269. 269export function triage(log) {
  270. 270 const lines = log.split(/\r?\n/);
  271. 271 const matches = [];
  272. 272 for (const sig of SIGNATURES) {
  273. 273 for (let i = 0; i < lines.length; i++) {
  274. 274 const m = sig.patterns.map((p) => p.exec(lines[i])).find(Boolean);
  275. 275 if (!m) continue;
  276. 276 const capture = m[1]?.trim() || null;
  277. 277 matches.push({
  278. 278 id: sig.id,
  279. 279 title: sig.title,
  280. 280 line: i + 1,
  281. 281 excerpt: mask(lines[i].trim()).slice(0, 300),
  282. 282 cause: fill(sig.cause, capture),
  283. 283 fix: sig.fix.map((f) => fill(f, capture)),
  284. 284 });
  285. 285 break;
  286. 286 }
  287. 287 }
  288. 288 matches.sort((a, b) => a.line - b.line);
  289. 289 // Missing modules and env vars usually explain later prerender, type and command errors.
  290. 290 const primary = matches[0] ?? null;
  291. 291 let firstError = null;
  292. 292 for (let i = 0; i < lines.length; i++) {
  293. 293 if (GENERIC_ERROR.test(lines[i]) && !NOISE.test(lines[i])) {
  294. 294 firstError = { line: i + 1, text: mask(lines[i].trim()).slice(0, 300) };
  295. 295 break;
  296. 296 }
  297. 297 }
  298. 298 return { detected: detect(log), lines: lines.length, primary: primary?.id ?? null, first_error: firstError, matches };
  299. 299}
  300. 300
  301. 301function toMarkdown(r) {
  302. 302 const d = r.detected;
  303. 303 const out = [
  304. 304 "# Deploy triage",
  305. 305 "",
  306. 306 `Platform: ${d.platform} | Framework: ${d.framework} | Package manager: ${d.package_manager} | Node: ${d.node ?? "not shown"}`,
  307. 307 "",
  308. 308 ];
  309. 309 if (r.first_error) out.push(`First error line (${r.first_error.line}): \`${r.first_error.text.replace(/`/g, "'")}\``, "");
  310. 310 if (!r.matches.length) {
  311. 311 out.push("No known failure pattern matched. Read the lines around the first error above, and paste 30 lines before it if this is a partial log.", "");
  312. 312 return out.join("\n");
  313. 313 }
  314. 314 r.matches.forEach((m, i) => {
  315. 315 out.push(`## ${i === 0 ? "Most likely cause" : `Also seen`}: ${m.title}`, "", `Line ${m.line}: \`${m.excerpt.replace(/`/g, "'")}\``, "", m.cause, "", "Fix:", "");
  316. 316 m.fix.forEach((f, j) => out.push(`${j + 1}. ${f}`));
  317. 317 out.push("");
  318. 318 });
  319. 319 return out.join("\n");
  320. 320}
  321. 321
  322. 322function write(path, text) {
  323. 323 mkdirSync(dirname(path), { recursive: true });
  324. 324 writeFileSync(path, text);
  325. 325}
  326. 326
  327. 327function main() {
  328. 328 const args = parseArgs(process.argv.slice(2));
  329. 329 let log;
  330. 330 if (args.input === "-") log = readFileSync(0, "utf8");
  331. 331 else if (!existsSync(args.input)) {
  332. 332 console.error(`No log at ${args.input}. Save the failed build log there (copy it from the deploy page), or pipe it in with "-".`);
  333. 333 process.exit(2);
  334. 334 } else log = readFileSync(args.input, "utf8");
  335. 335 if (!log.trim()) {
  336. 336 console.error("The log is empty.");
  337. 337 process.exit(2);
  338. 338 }
  339. 339 const report = triage(log);
  340. 340 const md = toMarkdown(report);
  341. 341 if (args.json) write(args.json, JSON.stringify(report, null, 2) + "\n");
  342. 342 if (args.md) write(args.md, md);
  343. 343 if (!args.json && !args.md) console.log(md);
  344. 344 else console.log(`${report.matches.length} known patterns. Most likely: ${report.primary ?? "none matched"}.`);
  345. 345}
  346. 346
  347. 347main();
Sign in to comment on a line