SIGKILL or Out of Memory (OOM) errors on Vercel generally point towards memory-related issues, often resulting from the limitations of the Vercel build container. If you're encountering this error, don't worry — with a few tweaks and optimizations, you can prevent these errors from surfacing.
Why Builds Fail Due to Memory Issues
Each Vercel build container is allocated 8192 MB of memory. When your project overruns this, a SIGKILL or OOM error may be thrown. Memory can be consumed by various project elements, including code, dependencies, assets, or processes running during build time.
Common causes of these errors include:
- Heavy memory consumption: Large-scale projects, or ones loaded with numerous dependencies, can easily consume memory.
- Multiple API builds: Running multiple builds concurrently uses more memory. In Next.js, for instance, every API route is built as a Serverless Function, increasing concurrent processes.
- Large data handling: Massive datasets or high-resolution assets naturally use more memory during processing.
- Inefficient code: Code that inadvertently creates many objects, or that doesn't free up memory, can rapidly eat up resources.
- External services: Overuse or poor optimization of calls to third-party services during build.
Steps To Reduce Memory Overhead
1. Static Page Generation
If you're using Next.js, getStaticPaths
allows you to control which pages are generated during the build. The paths that you include will be generated at build time, while the rest of the pages can be generated on demand using fallback
.
You can significantly decrease your build times and memory consumption by not pre-rendering any pages during the build and instead generating all static pages on demand. When deployed to Vercel, you can further extend this by pre-rendering pages for only production builds. This keeps your iteration cycles fast for small changes but opts for longer production builds to pre-render your static pages. This flexibility is particularly helpful for sites with hundreds/thousands of static pages.
Learn more about getStaticPaths.
2. Incremental Static Regeneration (ISR)
Incremental Static Regeneration (ISR) allows you to create or update content without redeploying your site. This not only ensures that your site remains up-to-date but also offers memory-related advantages:
- Staggered builds will reduce memory overhead. Traditional full-site builds demand memory for processing every piece of content simultaneously. In contrast, ISR focuses only on new or updated content.
- Faster builds will minimize continuous memory utilization. With ISR, pages have the option to defer their generation either on-demand or through an API. This means that instead of building every page during the deployment phase, some pages can be built when they're actually requested by users or when data changes. By reducing the number of pages built simultaneously, you not only achieve faster build times but also spread out memory usage.
Learn more about Incremental Static Regeneration.
3. Optimize Images & Assets
Large assets, especially high-resolution images, play a significant role in the overall memory consumption of a project during the build process. When these assets are being processed, converted, or optimised as part of the build pipeline, they demand a significant chunk of the available memory. This is particularly true for web applications that employ real-time image processing or transformations during the build.
To reduce memory overhead caused by images and assets:
- Reduce file sizes using tools like
ImageOptim
to manually compress images without a noticeable quality loss. - Integrate image compression tools into your build process. Libraries like
imagemin
can be used with plugins tailored for specific image types (JPEG, PNG, SVG, etc.). - Consider using modern web formats, such as WebP, for better compression than older formats.
4. Update Next.js Version
If you're using Next.js on your Vercel Deployment, we recommend running v14.1.2 or higher. Newer Next.js versions come with performance improvements and optimizations to reduce memory overhead.
5. Invalidate Build Cache
Clearing your Vercel Deployment's build cache can sometimes alleviate these errors if the build cache has become excessively large or corrupt. There's a few different ways to clear your project's build cache:
- Use the Redeploy button for the specific deployment in the Project's Deployments page. In the popup window that follows, leave the checkbox Use existing Build Cache unchecked.
- Use
vercel --force
with Vercel CLI. - Use the Environment Variable
VERCEL_FORCE_NO_BUILD_CACHE
with a value of1
. - Use the Environment Variable
TURBO_FORCE
with a value oftrue
on your project to skip Turborepo Remote Cache. - Use the
forceNew
optional query parameter with a value of1
when creating a new deployment with the Vercel API.
6. Force Single API Builds
If you suspect multiple API builds to be the problem, you can force Vercel to execute one build at a time, which can help prevent memory overload. To do this, set the FORCE_PARALLEL_BUILDS
environment variable to 1
.
7. Review & Manage Dependencies
Redundant or heavy dependencies in a project can stealthily degrade its efficiency, which is especially true for projects that have grown and evolved over time. Bloated dependencies can demand a significant chunk of the available memory during the build process and lead to a SIGKILL error.
- The
node_modules
directory can grow substantially, sometimes including unnecessary or deprecated packages. pnpm list
,npm ls
oryarn list
will view a tree of your installed packages and their dependencies.- Consider using
npm-check
ordepcheck
to identify unused or missing dependencies. - Some libraries are heavy for their functionality. Sites like
Bundlephobia
can show the footprint of npm packages. Look for lighter alternatives when possible. - Ensure you aren't including multiple versions or duplicate dependencies to your project. Use
pnpm dedupe
,npm dedupe
oryarn dedupe
to help identify instances of this. - Keep your dependencies up-to-date, as newer versions might have optimizations. Use
pnpm outdated
,npm outdated
oryarn outdated
to identify and then update outdated dependencies.
8. Analyze Bundles
Bundles can also inadvertently increase memory overhead. During build time, tasks like transpiling, code splitting, and source map generation can intensify memory demand. You can use tools like webpack-bundle-analyzer to generate visualizations of what’s in your webpack bundle.
When analyzing bundles, consider the following:
- Are any large libraries tree-shakable?
- Are you depending on deprecated libraries?
- Does the report show any large bundles?
- Webpack suggests keeping bundles under 250kb before minification. If bundles exceed this size, consider code splitting and possibly lazy loading for certain parts.
9. Limit Memory Size for Node (Experimental)
Limiting the allocated memory size will make Node.js more aggressive with its garbage collection process, which can alleviate memory errors for some projects. To limit the memory size for Node.js, add the following before your build command: NODE_OPTIONS="--max-old-space-size=6144"
For example:
NODE_OPTIONS="--max-old-space-size=6144" && next build
10. Disable Webpack or Force Webpack Compiler to Run Separately (Experimental)
Some customers may see benefit from leveraging an experimental flag next.config.js flag, which forces the webpack compiler to be run in a separate worker rather than in the main process itself:
{ "experimental": { "webpackBuildWorker": true }}
You may also disable webpack the cache entirely by adding the following config to next.config.js:
webpack: { cache = Object.freeze({ type: 'memory', });}
Conclusion
Memory errors can be frustrating and difficult to pin down, but with the right approach and optimizations in place, you can prevent them from occurring. Regularly reviewing and optimizing your project is key to ensuring smooth and efficient builds on Vercel.
If you've tried the above steps and still face issues, don't hesitate to reach out to our support team for further assistance.