Backstage build "JavaScript heap out of memory" in CI

A full Backstage build type-checks and bundles many workspaces at once, which can exceed Node default heap on a small runner. Node aborts with a FATAL heap error, sometimes surfacing as exit code 137 when the OS kills the process.

What this error means

The build dies with "FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory" or the step ends abruptly with exit code 137.

<--- Last few GCs --->
[1234:0x...] FATAL ERROR: Reached heap limit Allocation failed -
JavaScript heap out of memory
 1: 0x... node::Abort()
error Command failed with exit code 1.

Common causes

Default Node heap is too small for the monorepo

Type-checking and bundling every workspace together allocates more than the default old-space limit on a 2-core runner.

A memory-constrained runner or container

A small runner or a container with a low memory cap gives Node little headroom, so the OOM killer sends exit 137.

How to fix it

Raise the heap with NODE_OPTIONS

1. Set NODE_OPTIONS to raise the old-space limit for the build step.
2. Size it to the runner memory (for example 4096 on a 7 GB runner).
3. Re-run the build with the larger heap.

env:
  NODE_OPTIONS: --max-old-space-size=4096

Use a larger runner for the build stage

If the build genuinely needs more memory, run it on a larger runner rather than pushing the heap past physical RAM.

runs-on: ubuntu-latest-8-cores

How to prevent it

• Set --max-old-space-size for the build in NODE_OPTIONS.
• Size the heap to the runner, staying below physical memory.
• Split type check and build steps to reduce peak allocation.

Related guides