Go Compiler OOM - Fix "out of memory" During Build in CI

The Go compiler ran out of memory while building. On a small runner, a large generated package, heavy parallelism, or a memory-hungry dependency can exhaust RAM and get the process OOM-killed.

What this error means

A build dies with fatal error: runtime: out of memory, or a step ends abruptly with signal: killed and no compile error. It is often package- or parallelism-dependent and may pass on a larger runner.

go build output

fatal error: runtime: out of memory
# or, OOM-killed by the OS:
go build github.com/org/app/internal/generated: signal: killed

Common causes

Too much build parallelism for the runner

Go compiles packages in parallel up to GOMAXPROCS/-p. On a small runner, many concurrent compilations can exceed available memory.

A very large or generated package

A huge auto-generated file or a package with enormous functions can spike the compiler’s memory use for that single unit.

How to fix it

Limit build parallelism

Lower the number of packages compiled at once so peak memory stays within the runner’s limit.

Terminal

go build -p 2 ./...

Use a larger runner

When the build genuinely needs more RAM, run it on a higher-memory runner.

.github/workflows/ci.yml

jobs:
  build:
    runs-on: ubuntu-latest-4-cores   # or a larger custom runner

Split or shrink the offending package

Identify which package OOMs (the build names it before the kill).
Break a massive generated file into smaller ones, or reduce generated bloat.
Re-run with -p 1 to confirm it is parallelism vs a single huge unit.

How to prevent it

Size runners to your largest package’s compile footprint.
Cap -p on memory-constrained runners.
Keep generated code split into reasonably sized files.