RunbooksBuild OOM

Next.js build runs out of memory

Applies to: core

Symptom

pnpm build hangs for minutes, then exits with one of:

<--- Last few GCs --->
<--- JS stacktrace --->
FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory
Killed
error: script "build" failed with exit code 137

Exit code 137 means the OOM killer terminated Node.

Likely cause

apps/web is a very large Next.jsNext.jsReact framework used by HiveCFM Core. Handles routing, server rendering, and API routes in one bundle. app — the root script in hivecfm-core/apps/web/package.json already ships with a raised heap:

"build": "cross-env NODE_OPTIONS=--max-old-space-size=8192 next build"

If you see OOM despite this, it means the machine (or Docker memory limit) cannot back an 8 GB heap, or you are building the whole monorepo in parallel and something else is eating RAM at the same moment next build peaks.

Fix

Check the actual memory available

free -h                 # Linux
vm_stat | head          # macOS
docker info | grep -i memory   # Docker Desktop limit

Next’s full build needs roughly 8 GB of RAM for the Node process alone. If the host or the Docker VM has less, the OS will kill the build.

Build only the web workspace

Skip turbo’s parallel build and run only @hivecfm/web:

cd /home/ubuntu/AG-DEV/hivecfm-core
pnpm --filter @hivecfm/web build

Raise the heap ceiling further

If RAM is available but the heap still fills, bump --max-old-space-size beyond 8 GB for this invocation:

NODE_OPTIONS=--max-old-space-size=12288 pnpm --filter @hivecfm/web build

Leave the committed script alone — override per-run via the env var.

Raise Docker Desktop’s memory (Docker builds only)

Docker Desktop caps the Linux VM at a small default (often 2 GB). Raise it to at least 10 GB under Settings → Resources → Memory, apply and restart, then rebuild:

docker compose build --no-cache hivecfm-core

Verify

pnpm --filter @hivecfm/web build
echo $?        # 0
ls apps/web/.next   # build output present

Prevent

  • Do not lower the committed --max-old-space-size=8192 in apps/web/package.json — it is sized for the real build.
  • On CI, pin a runner with at least 8 GB of memory for web builds; smaller runners OOM intermittently.
  • Close other memory-hungry processes (Chrome, IDE language servers) before running a full build locally.
Port conflictsPostgres refused