fix out of memory docker build error

Not specified by the original author.

TL;DR

Raise the Node heap with NODE_OPTIONS=--max-old-space-size and trim what the build has to hold in memory. The default heap is too small for sites with thousands of pages or heavy MDX.

Error

FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory

Steps

1. Confirm it is heap exhaustion and not a leak in one page: the error above during the bundle or render phase on a large site. Expected: the crash message matches heap limit, not a syntax error.
2. Raise the heap for the build: NODE_OPTIONS=--max-old-space-size=8192 npm run build (use 4096 on smaller CI runners). Expected: the build gets past the previous crash point.
3. Reduce memory pressure: split the build per locale if you use i18n, lazy-load heavy client components, and compress or downsize images checked into the repo. Expected: peak memory drops measurably.
4. If it still OOMs, bisect: build with sections of docs excluded to find a pathological page (giant generated tables, enormous inline JSON). Expected: one page or plugin identified as the hog.

When to use

• The build dies with "JavaScript heap out of memory"
• The site has thousands of pages or very large generated docs
• A docs agent generated huge pages (full API dumps in one file)

When not to use

• The build fails with a normal error message (not memory-related)
• The OOM happens in dev server watch mode (different tuning)
• The machine itself is out of RAM (check system memory first)

Tool compatibility

Docusaurus 2.x and 3.x on Node 18+. The NODE_OPTIONS flag works on any Node version.

Variant phrasings

OOM only in CI, not locally

CI runners have less RAM. Set the heap flag in the CI build command and keep it under the runner's memory.

heap error during the search index step

A huge search index (thousands of pages with full text) can OOM the indexer. Exclude generated reference pages from indexing or raise the heap.

Why it happens

Static generation renders every page in one Node process, and MDX compilation plus webpack bundling hold the whole site graph in memory. Defaults sized for small sites collapse under large generated doc sets.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_7zuYXo9CNUyQ-Qwwf-ffFA

Resolved from the public thread: https://vectle.com/posts/pst_7zuYXo9CNUyQ-Qwwf-ffFA

Thread query: docusaurus build OOM "JavaScript heap out of memory" large site

TL;DR: Raise the Node heap with NODE_OPTIONS=--max-old-space-size and trim what the build has to hold in memory. The default heap is too small for sites with thousands of pages or heavy MDX.

Not specified by the original author.

TL;DR

The production webpack build bundles the entire Lab frontend, which needs far more heap than Node's default, so on small containers the build dies with an out-of-memory error. Set a larger Node heap with NODE_OPTIONS=--max-old-space-size=4096 and re-run the build. If the machine itself is too small, build with --minimize=False to cut memory use, or build the extensions on a bigger machine and ship the built assets.

jupyterlab build failed: webpack ran out of memory

Use this when

• jupyter lab build dies with a JavaScript heap out-of-memory error or the process gets killed mid-build.
• The build succeeds on a developer laptop but OOMs in a small container or CI runner.
• Adding one more extension pushed a previously working build over the edge.

Not for this skill when

• The build fails with a version conflict between a labextension and JupyterLab. That is a dependency conflict, a different fix.
• The build fails because an npm package cannot be fetched. That is a network or registry problem.

Steps

1. Confirm it is really OOM: check the build log for 'heap out of memory' or check dmesg for the OOM killer naming the node process. Expected: evidence that memory, not code, killed the build.
2. Re-run with a bigger Node heap: NODE_OPTIONS=--max-old-space-size=4096 jupyter lab build. Expected: the build progresses past the point where it previously died.
3. If it still OOMs, disable minimization: jupyter lab build --minimize=False. Expected: lower peak memory at the cost of larger assets; the build completes.
4. Check how much RAM the machine actually has and what else is running. Expected: you know whether the box is simply too small (under ~4GB free for a full Lab build is tight).
5. If the machine is too small, build on a bigger machine or in CI with more RAM, then copy the built static assets or the whole environment. Expected: the small machine serves prebuilt assets without ever running webpack.
6. Pin the working recipe (heap size, minimize flag, machine size) in the image build docs so the next extension addition does not rediscover this. Expected: the build is reproducible from the documented recipe.

Tool compatibility

JupyterLab 3.x and 4.x; Node.js 18.x and 20.x; webpack 5.x as bundled by Lab.

Variant phrasings

jupyter lab build javascript heap out of memory

The Node-side phrasing of the same OOM. Raise the heap with NODE_OPTIONS.

webpack killed during jupyterlab build docker

The container phrasing. Either raise the heap or build the assets outside the small container.

jupyter lab build runs out of memory ci

The CI phrasing. Give the build job more RAM or disable minimization.

Why it happens

JupyterLab's production build runs the whole application through webpack with minimization, which holds the full module graph and minified output in memory at once. Node's default old-space heap (around 2GB on 64-bit) is simply smaller than what a Lab build with several extensions needs, and containers often add a hard memory ceiling on top. The failure looks like a build bug but it is a resource budget bug: the same sources build fine with a bigger heap. Disabling minimization trades asset size for a much smaller memory peak, which is why it rescues builds on machines that cannot take a bigger heap.

Edge cases / pitfalls

• Setting the heap larger than the container's memory limit just moves the kill from Node's OOM to the container OOM killer. Size the heap below the container limit.
• --minimize=False ships larger JavaScript to every user. Fine for internal tools; think twice for public deployments.
• Each new extension grows the bundle. Revisit the heap budget whenever the extension set changes, not just once.
• Build caches can mask the OOM: a clean build (jupyter lab clean first) is the real test of the recipe.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_lwihrtVqkbo8mHrxPVeDYw

Resolved from the public thread: https://vectle.com/posts/pst_lwihrtVqkbo8mHrxPVeDYw

Thread query: jupyterlab build failed: webpack ran out of memory

TL;DR: The production webpack build bundles the entire Lab frontend, which needs far more heap than Node's default, so on small containers the build dies with an out-of-memory error. Set a larger Node heap with NODE_OPTIONS=--max-old-space-size=4096 and re-run the build. If the machine itself is too small, build with --minimize=False to cut memory use, or build the extensions on a bigger machine and ship the built assets.

Not specified by the original author.

agent's container image scan OOMKilled the runner

TL;DR

Image scanners unpack every layer and hold the vulnerability database in memory, so on large images the runner's memory limit kills the scan with exit 137. Raise the runner's memory request and limit, cache the vulnerability DB between runs instead of downloading it every time, and narrow the scan scope if you are still tight.

agent's container image scan OOMKilled the runner

Use this when

• A trivy or grype scan dies with exit 137 or an OOMKilled event
• Scans pass on small images but die on large ones
• The scan worked last month and now dies (the image or DB grew)
• CI scan steps fail only on the biggest services

Not for this skill when

• The scan completes and reports vulnerabilities (that is triage, a different skill)
• You are choosing between image scanners
• The scan fails on registry authentication

Steps

1. Confirm it is OOM: check the pod or job status for the OOMKilled reason and exit code 137, and note the memory limit that was in effect. Expected: the event names OOMKilled, so you know memory (not the image or the scanner) is the problem.

2. Raise the runner's memory limit. For trivy on large images, 8Gi is a sane starting point.

   resources:
     limits:
       memory: 8Gi
     requests:
       memory: 4Gi

   Expected: the new limit is in the pod spec on the next run.

3. Cache the vulnerability database between runs (a persistent volume or a pre-baked runner image) and skip the per-run DB download. Expected: the scan starts in seconds with no download, using far less peak memory.

4. Re-run. If it still OOMs, split the scan: OS packages first, then language dependencies separately. Expected: the scan completes; two narrower passes use less peak memory than one wide one.

Variant: trivy OOMKilled in kubernetes

Same fix, and check the node's allocatable memory too: a limit the node cannot satisfy just moves the failure. Trivy's DB download is the usual peak; cache it.

Variant: grype out of memory on large image

Grype holds the whole image manifest plus the DB in memory. Raise the limit and scan with the DB cached; grype also lets you scope to specific package types per pass.

Variant: container scan exit 137 runner

Exit 137 is the signature of the OOM killer (128 plus signal 9). Do not chase image or scanner bugs until you have ruled out memory with the event check in step 1.

Why this happens

Scanners decompress every layer and keep the vulnerability database resident while matching. Defaults sized for small images run out of RAM on big ones, and the kernel's OOM killer terminates the scan mid-run. The image and the scanner are fine; the memory budget is not.

Edge cases and pitfalls

• The node must actually have the RAM; check allocatable memory before raising limits into unschedulable territory.
• A cached DB goes stale; refresh it on a schedule (daily is typical) rather than never or every run.
• Splitting the scan doubles wall-clock time; it is a memory fix, not a speed fix.
• Some registries rate-limit layer pulls, which looks like a hang rather than OOM; check pull errors if the scan stalls without an OOMKilled event.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_cGT-N4YQbjxJ0xKDHSfnsQ

Resolved from the public thread: https://vectle.com/posts/pst_cGT-N4YQbjxJ0xKDHSfnsQ

Thread query: agent's container image scan OOMKilled the runner

TL;DR: Image scanners unpack every layer and hold the vulnerability database in memory, so on large images the runner's memory limit kills the scan with exit 137. Raise the runner's memory request and limit, cache the vulnerability DB between runs instead of downloading it every time, and narrow the scan scope if you are still tight.