Troubleshooting Builds Failing with SIGKILL or Out of Memory Errors

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 of 1.
• Use the Environment Variable TURBO_FORCE with a value of true on your project to skip Turborepo Remote Cache.
• Use the forceNew optional query parameter with a value of 1 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 or yarn list will view a tree of your installed packages and their dependencies.
• Consider using npm-check or depcheck 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 or yarn dedupe to help identify instances of this.
• Keep your dependencies up-to-date, as newer versions might have optimizations. Use pnpm outdated, npm outdated or yarn 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.