{"record":{"id":"ec534af05467c67e","repo":"mastra-ai/mastra","slug":"fail-build-script","errorCode":"FAIL_BUILD_SCRIPT","errorMessage":"FAIL_BUILD_SCRIPT","messagePattern":"FAIL_BUILD_SCRIPT","errorType":"error_code","errorClass":"MastraError","httpStatus":null,"severity":"error","filePath":"deployers/cloud/src/utils/deps.ts","lineNumber":134,"sourceCode":"        id: 'FAIL_CUSTOM_INSTALL_COMMAND',\n        category: 'USER',\n        domain: 'DEPLOYER',\n      },\n      error,\n    );\n  }\n}\n\nexport async function runScript({ scriptName, path, args }: { scriptName: string; path: string; args?: string[] }) {\n  const pm = detectPm({ path });\n  logger.info('Running script', { script: scriptName, pm });\n  const { success, error } = await runWithExeca({\n    cmd: pm,\n    args: pm === 'npm' ? ['run', scriptName, ...(args ?? [])] : [scriptName, ...(args ?? [])],\n    cwd: path,\n  });\n  if (!success) {\n    throw new MastraError(\n      {\n        id: 'FAIL_BUILD_SCRIPT',\n        category: 'USER',\n        domain: 'DEPLOYER',\n      },\n      error,\n    );\n  }\n}\n\nexport async function runBuildCommand({ command, path }: { command: string; path: string }) {\n  logger.info('Running build command', { command });\n  const { success, error } = await runWithExeca({ cmd: 'sh', args: ['-c', command], cwd: path });\n  if (!success) {\n    throw new MastraError(\n      {\n        id: 'FAIL_BUILD_COMMAND',\n        category: 'USER',","sourceCodeStart":116,"sourceCodeEnd":152,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/deployers/cloud/src/utils/deps.ts#L116-L152","documentation":"runScript runs a package.json script via the package manager (`npm run <script>` for npm, `<pm> <script>` otherwise) in the given path. Non-zero exit throws a MastraError with id FAIL_BUILD_SCRIPT (category USER, domain DEPLOYER) wrapping the execa error. This is how cloud deploy executes build steps defined in your package.","triggerScenarios":"Calling runScript (e.g. to run a `build` script) during deploy when the script exits with an error — compilation failure, missing script name, or failing test/lint step chained into it.","commonSituations":"TypeScript/build errors in the bundled output; script name not present in the output directory's package.json; memory exhaustion (OOM) on large builds in constrained CI; scripts that depend on dev-only env vars.","solutions":["Read the wrapped execa stderr to see the script's failure output and fix the underlying build error","Verify the script exists in the output directory's package.json","Increase Node memory for the build (NODE_OPTIONS=--max-old-space-size=4096)","Remove local-only steps (tests, lint) from the build script used in deploy"],"exampleFix":"// before\n{ \"scripts\": { \"build\": \"tsc && vitest run\" } } // tests fail in deploy env\n// after\n{ \"scripts\": { \"build\": \"tsc\", \"test\": \"vitest run\" } }","handlingStrategy":"try-catch","validationCode":"node -e \"const p=require('./package.json'); process.exit(p.scripts?.[scriptName] ? 0 : 1)\" || echo 'script missing'","typeGuard":null,"tryCatchPattern":"try {\n  await runScript({ path, pm, scriptName, args });\n} catch (err) {\n  if (err instanceof MastraError && err.id === 'FAIL_BUILD_SCRIPT') {\n    console.error('Script failed:', err.cause); // script stdout/stderr here\n  } else throw err;\n}","preventionTips":["Run the build script locally with production env before deploying","Ensure NODE_OPTIONS=--max-old-space-size is set for large builds","Keep deploy build scripts free of local-only steps (tests, watches)","Confirm the script exists in the output directory's package.json"],"tags":["build","deployment","scripts","subprocess"],"backgroundTag":"build-script-failed","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}