Fix 'JavaScript Heap Out of Memory' for Gatsby on Netlify

$ FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory

Also appears as:

  • ENOMEM: not enough memory
  • FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed
  • JavaScript heap out of memory gatsby build
  • Killed - gatsby build out of memory

Symptoms

  • Build crashes during 'gatsby build' step
  • Build log shows memory allocation errors
  • Build works locally but fails on Netlify
  • Build fails at the image processing or page generation stage

What Causes This Error

Too many images being processed simultaneously

Common

Gatsby's sharp-based image processing loads all images into memory. Sites with hundreds of images can easily exceed Netlify's memory limit during the build.

Large number of pages generated at build time

Common

Gatsby keeps all page data in memory during the build. Sites with thousands of pages (especially with heavy data) can exhaust the available heap space.

Heavy GraphQL queries

Occasional

Large GraphQL queries that fetch all data at once hold everything in memory. This compounds with the page count as each page might execute heavy queries.

Memory leaks in plugins

Occasional

Some Gatsby plugins have known memory leaks that accumulate during the build process. Older versions of gatsby-plugin-image and source plugins are common culprits.

How to Fix It

Fix 1: Increase Node.js memory limit

  1. Go to your Netlify site's Environment Variables settings
  2. Add or update the NODE_OPTIONS variable
  3. Set the value to increase the heap size
  4. Trigger a new deploy
Netlify environment variable
NODE_OPTIONS=--max_old_space_size=4096

Verify: Redeploy and check if the build completes. If it still fails, try 8192 instead of 4096.

Fix 2: Optimize image processing

  1. Reduce the number of image sizes/formats generated
  2. Use gatsby-plugin-image with constrained layout instead of fullWidth where possible
  3. Compress source images before adding them to your project
  4. Process images in smaller batches using GATSBY_CPU_COUNT=1
Netlify environment variables
NODE_OPTIONS=--max_old_space_size=4096
GATSBY_CPU_COUNT=2

Verify: Rebuild and check if memory usage stays within limits during the image processing step.

Fix 3: Enable incremental builds

  1. Install the gatsby-plugin-netlify build cache plugin
  2. Enable Gatsby's experimental incremental builds
  3. This reduces memory usage by only rebuilding changed pages
Netlify environment variable
GATSBY_EXPERIMENTAL_PAGE_BUILD_ON_DATA_CHANGES=true

Verify: After the first full build, subsequent builds should be faster and use less memory.

Fix 4: Optimize GraphQL queries

  1. Use GraphQL query limits and pagination
  2. Avoid fetching all nodes at once in gatsby-node.js
  3. Use createPages pagination to batch page creation
  4. Remove unused GraphQL fields from your queries
gatsby-node.js (paginated queries)
exports.createPages = async ({ graphql, actions }) => {
  const { createPage } = actions
  const result = await graphql(`
    query {
      allMarkdownRemark(limit: 100, skip: 0) {
        nodes {
          fields { slug }
        }
      }
    }
  `)
  // Process in batches
}

Verify: Check that queries fetch only necessary data and pages are created in batches.

How to Prevent This

1.

Monitor your build memory usage in Netlify's build logs — look for peak memory usage.

2.

Optimize images before adding them to your repository (compress, resize to maximum needed dimensions).

3.

Keep Gatsby and its plugins updated — newer versions often have better memory management.

4.

Use the Netli.fyi app to monitor build health and catch memory issues early.

5.

Consider migrating from Gatsby to Astro or Next.js for very large sites — they handle memory more efficiently at scale.

Perttu Lähteenlahti

Perttu Lähteenlahti

Developer Advocate at RevenueCat and creator of Netli.fyi. Building on Netlify since 2019. Writes from hands-on experience deploying dozens of production sites.

Manage Netlify on the go

Download Netli.fyi and monitor your sites, check deploys, and manage your projects from anywhere.

Google Play