Gatsby build fail on Node v20 but works on v16

Hello! I’m worried about running into problems in the future regarding this. In my Gatsby netlify.toml file and in the netlify environment variable settings I have the node version set to v20.0.0 (also locally on my laptop) but the build fails on Netlify. BUT when I create an nvmrc file and set that to 16, the build is successful!

Trying to figure out why this worked. What version of node does netlify current support?

Thank you!

Heres the build log for when it failed btw

5:04:46 PM: Netlify Build                                                 
5:04:46 PM: ────────────────────────────────────────────────────────────────
5:04:46 PM: ​
5:04:46 PM: ❯ Version
5:04:46 PM:   @netlify/build 29.11.5
5:04:46 PM: ​
5:04:46 PM: ❯ Flags
5:04:46 PM:   baseRelDir: true
5:04:46 PM:   buildId: 64656b6685e24513eebfa944
5:04:46 PM:   deployId: 64656b6685e24513eebfa946
5:04:46 PM: ​
5:04:46 PM: ❯ Current directory
5:04:46 PM:   /opt/build/repo
5:04:46 PM: ​
5:04:46 PM: ❯ Config file
5:04:46 PM:   /opt/build/repo/netlify.toml
5:04:46 PM: ​
5:04:46 PM: ❯ Context
5:04:46 PM:   production
5:04:46 PM: ​
5:04:46 PM: build.command from netlify.toml                               
5:04:46 PM: ────────────────────────────────────────────────────────────────
5:04:46 PM: ​
5:04:46 PM: $ gatsby build
5:04:47 PM: error There was a problem loading plugin "gatsby-plugin-netlify". Perhaps you need to install its package?
5:04:47 PM: Use --verbose to see actual error.
5:04:47 PM: not finished open and validate gatsby-configs, load plugins - 0.018s
5:04:47 PM: ​
5:04:47 PM: "build.command" failed                                        
5:04:47 PM: ────────────────────────────────────────────────────────────────
5:04:47 PM: ​
5:04:47 PM:   Error message
5:04:47 PM:   Command failed with exit code 1: gatsby build (
5:04:47 PM: ​
5:04:47 PM:   Error location
5:04:47 PM:   In build.command from netlify.toml:
5:04:47 PM:   gatsby build
5:04:47 PM: ​
5:04:47 PM:   Resolved config
5:04:47 PM:   build:
5:04:47 PM:     command: gatsby build
5:04:47 PM:     commandOrigin: config
5:04:47 PM:     environment:
5:04:47 PM:       - NODE_VERSION
5:04:47 PM:       - RUBY_VERSION
5:04:47 PM:     publish: /opt/build/repo/public
5:04:47 PM:     publishOrigin: config
5:04:49 PM: Build failed due to a user error: Build script returned non-zero exit code: 2
5:04:49 PM: Failing build: Failed to build site
5:04:49 PM: Failed during stage 'building site': Build script returned non-zero exit code: 2 (
5:04:50 PM: Finished processing build request in 53.117s

The deploy you’ve presented above is using Node 16, not Node 20. Unless you need the latest features of Node desperately, I would usually not recommend using the latest version. You should use the latest LTS version (currently Node 18) as the ecosystem usually takes some time to catch-up to the latest release.

With that being said, Netlify supports any Node version that’s publicly available, but the dependencies you might be using might or might not support the version you’re trying to use.


More than Node Version, you need to be worried about your Gatsby version. Gatsby 5 is the current latest and you’re using Gatsby 3. Gatsby 3 is not actively supported anymore: Gatsby Framework Version Support | Gatsby