How do I resolve "Out of memory" errors in my Amplify build deployment?

Short description

When you deploy a build in the Amplify console, Amplify creates a temporary compute container with 4 virtual CPUs (vCPUs) and 8 GB of RAM. If your build requires more memory than the default 8 GB, then you might receive one of the following out-of-memory errors:

"JavaScript heap out of memory"

"FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed"

"SIGKILL directive"

Memory consumption varies based on the package manager, build tools, framework, and overall project complexity.

Resolution

Identify your memory requirements

To check your application's memory usage and measure your build's memory consumption, complete the following steps:

1. Open Windows Terminal or PowerShell in your project directory.
2. To identify peak memory usage, run the following command based on your operating system (OS).
   Linux or macOS:

   /usr/bin/time -l npm run build

   Windows:

   path = (Get-Location).Path; job = Start-Job -ScriptBlock { Set-Location -Path Using:path; npm run build }; maxMemory = 0; while (job.State -eq 'Running') { currentMemory = (Get-Process -Name 'node' -ErrorAction SilentlyContinue | Measure-Object -Property WorkingSet64 -Sum).Sum; if (currentMemory -gt maxMemory) { maxMemory = currentMemory }; Start-Sleep -Seconds 1 }; Wait-Job job; Receive-Job job; Write-Host "Peak Memory Usage: ([math]::Round(maxMemory / 1MB, 2)) MB"; Remove-Job job

To use Node.js to identify bottlenecks and locate memory-intensive operations, complete the following steps:

1. Open the command prompt in your project directory.

2. Run the following command to get the profiling command for your framework:

   React (CRA): node --prof node_modules/react-scripts/scripts/build.js Vite : node --prof node_modules/vite/bin/vite.js build
   Next.js : node --prof node_modules/next/dist/bin/next build
   Vue CLI : node --prof node_modules/@vue/cli-service/bin/vue-cli-service.js build

3. Run the following command to generate the analysis report:

   node --prof-process isolate-0x*.log > profile_report.txt

   Note**:** The analysis report shows time-related information about function calls and memory allocation for your build. Use this information to identify the operations that use the most resources and that you can optimize.

Update your Amplify configuration

Note: If you use an amplify.yml file in your GitHub repository, then you must update the file directly in the repository, not in the Amplify console.

Configure memory optimization environment variables

To optimize memory usage during the build process of large applications, add memory optimization environment variables to your build. Edit the build specifications and add the following environment variables to the preBuild section of your YAML configuration file, based on your application type:

• React applications:

  frontend:
    phases:
      preBuild:
        commands:
          - npm install
          - export NODE_OPTIONS=--max-old-space-size=5632
          - export GENERATE_SOURCEMAP=false
          - export INLINE_RUNTIME_CHUNK=false

  Note: NODE_OPTIONS=--max-old-space-size=5632 increases the Node.js heap memory quota to 5.5 GB and prevents out-of-memory errors during large builds. GENERATE_SOURCEMAP=false deactivates source map generation and reduces memory consumption and build time. INLINE_RUNTIME_CHUNK=false reduces memory overhead during bundling.
• Non-React applications:

  frontend:
    phases:
      preBuild:
        commands:
          - npm install
          - export NODE_OPTIONS=--max-old-space-size=5632

  Note: INLINE_RUNTIME_CHUNK=false reduces memory overhead during bundling. GENERATE_SOURCEMAP and INLINE_RUNTIME_CHUNK are specific to React applications.

Temporarily deactivate caching

To reduce memory usage during the build creation process, complete the following steps to temporarily deactivate caching:

1. Open the Amplify console.

2. Select your application.

3. Choose Hosting.

4. Choose Build settings.

5. Under App build specification, choose Edit.

6. Add # hashes to the cache section. Example configuration:

     #cache:
       #paths:
         #- node_modules/**/*
         #- .next/cache/**/*
         #- .npm/**/*

7. Choose Save.
   Note: When you deactivate caching, memory usage reduces but build time increases.

8. After the build completes, remove the # hashes from the cache section to reactivate caching. Example configuration:

     cache:
       paths:
         - node_modules/**/*
         - .next/cache/**/*
         - .npm/**/*

Upgrade your build container size

If your application requires more than 8 GB of RAM, then complete the following steps to increase the build instance size:

1. Open the Amplify console.

2. Select your application.

3. Choose Hosting.

4. Choose Build settings, and then choose Advanced settings.

5. Choose Edit.

6. Select your build instance type.

7. Choose Save.

8. Under App build specification, choose Edit.

9. Update the max-old-space-size parameter based on your instance type:
   Large (16 GiB):

   --max-old-space-size=14000

   Large (32 GiB):

   --max-old-space-size=28000

10. Choose Save.

11. In the navigation pane, choose Overview.

12. Select your application branch.

13. Select your latest deployment, and then choose Redeploy this version.

Note: To prevent build failures, reserve 1 GB of memory for system processes. For information about build instance pricing, see AWS Amplify pricing.