Go Compiler OOM - Fix "out of memory" During Build in CI
By Daniel Zoghalchali·Latchkey
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.
Frequently asked questions
What causes "compiler out of memory"?
Go compiles packages in parallel up to GOMAXPROCS/-p. On a small runner, many concurrent compilations can exceed available memory.
How do I fix compiler out of memory?
Lower the number of packages compiled at once so peak memory stays within the runner’s limit.
Can Latchkey fix this automatically?
Yes. Latchkey runs your GitHub Actions on managed runners that detect this failure, apply the fix, and retry the job automatically - self-healing is on by default.
