{"record":{"id":"57db92e03af2d897","repo":"mastra-ai/mastra","slug":"fail-build-command","errorCode":"FAIL_BUILD_COMMAND","errorMessage":"FAIL_BUILD_COMMAND","messagePattern":"FAIL_BUILD_COMMAND","errorType":"error_code","errorClass":"MastraError","httpStatus":null,"severity":"error","filePath":"deployers/cloud/src/utils/deps.ts","lineNumber":149,"sourceCode":"    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',\n        domain: 'DEPLOYER',\n      },\n      error,\n    );\n  }\n}\n","sourceCodeStart":131,"sourceCodeEnd":159,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/deployers/cloud/src/utils/deps.ts#L131-L159","documentation":"runBuildCommand executes an arbitrary build command via `sh -c <command>` in the given path and throws a MastraError with id FAIL_BUILD_COMMAND (category USER, domain DEPLOYER) if it exits non-zero, wrapping the execa error. It is the free-form counterpart to runScript for custom build pipelines in cloud deploys.","triggerScenarios":"Calling runBuildCommand with a command that fails in the deploy environment — unknown binary, failing compilation, or a chained command returning non-zero.","commonSituations":"Custom build command depends on tools absent from the deploy image; shell quoting issues in complex commands; environment variables not exported in non-interactive `sh -c`; genuinely failing build (type errors, missing assets).","solutions":["Re-run the exact command in the target path locally to see the failure","Check the wrapped execa error's stdout/stderr for root cause","Ensure all toolchain binaries are installed in the deploy image","Simplify quoting: put complex logic in a script file and invoke it"],"exampleFix":"// before\nawait runBuildCommand({ command: 'export NODE_ENV=production && nx build api', path }); // nx not in image\n// after\nawait runBuildCommand({ command: 'npm run build', path }); // uses local package script","handlingStrategy":"try-catch","validationCode":"sh -n -c \"$BUILD_COMMAND\" || echo 'invalid shell syntax'\ncommand -v ${BUILD_COMMAND%% *} >/dev/null || echo 'first binary missing'","typeGuard":null,"tryCatchPattern":"try {\n  await runBuildCommand({ command, path });\n} catch (err) {\n  if (err instanceof MastraError && err.id === 'FAIL_BUILD_COMMAND') {\n    console.error('Build command failed:', err.cause); // includes stdout/stderr\n  } else throw err;\n}","preventionTips":["Verify all toolchain binaries exist in the deploy image","Move complex logic into a script file to avoid quoting bugs","Export needed env vars explicitly; non-interactive sh does not source profiles","Test the identical command in CI before deploying"],"tags":["build","deployment","shell","subprocess"],"backgroundTag":"build-script-failed","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}