Build Failures
Triage dependency, typecheck, environment, and CI build failures.
When CI fails or local builds break, follow this triage process to identify and fix the root cause quickly.
Triage steps
- Identify the failing job and step in CI logs.
- Compare lockfile and dependency changes in the PR.
- Check for missing or incorrect environment variables.
- Run the same command locally to reproduce.
- Attach logs to the PR or support thread.
Local reproduction
pnpm install --frozen-lockfile
pnpm typecheck
pnpm buildCommon causes
| Symptom | Likely cause | Fix |
|---|---|---|
Module not found | Missing dependency or wrong import path | Check package.json and import statements |
| Type errors after upgrade | Breaking change in dependency | Check changelog, update types |
ENOENT .env | Missing env file in CI | Add secrets to GitHub Actions |
| Build timeout | Large bundle or slow tests | Check bundle analyzer, optimize imports |
EACCES permission error | File permission issue | Check Docker volume mounts |
CI debug tips
- Check the "Actions" tab in GitHub for full logs
- Re-run failed jobs with debug logging enabled
- Compare with the last successful build on
main - Ask in
#engineering-supportif stuck after 30 minutes