Vercel Build Doctor

Vercel Build Doctor

Synthex deploys to two Vercel projects under team unite-group: synthex (production) and synthex-sandbox. The GitHub commit status Vercel – synthex is the production gate. When it is red, the live site does not update. Never guess the cause — read the actual build log first.

Step 1 — Find the failed deployment

The Vercel CLI is often scoped to the wrong account (vercel projects ls returns nothing for unite-group). Use the GitHub commit status to get the deployment URL, then the REST API for logs.

# Which Vercel deploys failed, across recent main commits:
for sha in $(git log --format=%H -8 origin/main); do
  echo "=== ${sha:0:8} ==="
  gh api repos/CleanExpo/Synthex/commits/$sha/status \
    | python3 -c "import sys,json;[print(' ',s['context'],'|',s['state']) for s in json.load(sys.stdin).get('statuses',[]) if 'ercel' in s['context']]"
done

The last green commit bounds the regression: the break landed between it and the first red one.

Step 2 — Pull the real build log (Vercel REST API)

The CLI auth token lives at ~/Library/Application Support/com.vercel.cli/auth.json. Team unite-group = team_KMZACI5rIltoCRhAtGCXlxUf.

TOKEN=$(python3 -c "import json;print(json.load(open('$HOME/Library/Application Support/com.vercel.cli/auth.json'))['token'])")
TEAM=team_KMZACI5rIltoCRhAtGCXlxUf

# Most recent deployments + state + commit:
curl -s "https://api.vercel.com/v6/deployments?app=synthex&teamId=$TEAM&limit=8" \
  -H "Authorization: Bearer $TOKEN" | python3 -c "
import sys,json
for d in json.load(sys.stdin)['deployments']:
    m=d.get('meta',{})
    print(d['uid'], d.get('state'), m.get('githubCommitSha','')[:8], m.get('githubCommitMessage','')[:50])"

# Full build log for the failing deployment id (dpl_...):
DPL=dpl_xxxxxxxx
curl -s "https://api.vercel.com/v3/deployments/$DPL/events?teamId=$TEAM&builds=1&limit=1000" \
  -H "Authorization: Bearer $TOKEN" -o /tmp/vlogs.json
python3 -c "import json;[print(e.get('text','').rstrip()) for e in json.load(open('/tmp/vlogs.json')) if e.get('text','').strip()]" | tail -100

The last ~40 lines almost always carry the verdict. Look for the explicit Error: line and the Vercel "Build system report" footer (it names OOM events).

Step 3 — Classify the failure

OOM is the recurring one: the app keeps growing, so the webpack build drifts toward the memory ceiling and goes flaky (same commit passes on retry, fails on the next). A green retry is not a fix — treat any 137 as a real regression.

Step 4 — Fix, then verify locally before re-deploying

npm run type-check && npm run lint && npm test

For OOM specifically, reproduce the memory profile locally when possible:

NODE_OPTIONS=--max-old-space-size=8192 npx next build --webpack

Commit with the issue id, push, then re-run Step 1/2 against the new deployment and confirm READY (not ERROR) before claiming done. Paste the deployment state line — per .claude/rules/verification-gate.md, a "fixed" claim needs the tool output that proves it.

History (so we stop relearning this)

• 2026-06-17 — Production synthex builds failed from commit ca63dc17 (#516) onward with exit 137 / OOM; last green was #515. Cause: cumulative app growth pushed next build --webpack past the 16GB container. Flaky at the ceiling (69ce505e produced both an ERROR and a READY deployment). Fix: experimental.webpackMemoryOptimizations: true. The failures were not caused by the code in the intervening PRs — they were memory-ceiling drift.