Introduction

Gatsby.js is a popular open-source framework for building fast and modern websites. It uses React, GraphQL, and other modern web technologies to create high-performance websites. However, like any other project, it can come with its own set of challenges. In this article, we will explore a solution to one of the most common problems that you might encounter while upgrading a Gatsby.js project from version 4 to version 5 on Gatsby Cloud.

The Issue

When attempting to upgrade a Gatsby project from version 4 to version 5, it is crucial to update the Node.js version to at least 18.0.0. However, despite following the official documentation provided by Gatsby on upgrading Node.js, you may still fail and encounter an error:

ERROR Gatsby requires Node.js 18.0.0 or higher (you have v16.15.0).

This error occurs even though everything is properly configured. For some reason, the server fails to detect the changes.

The Solution

To address the issue of the Node.js version not changing as expected, we need to take an additional step: disabling the Gatsby Cloud Builds option.

This option, when enabled, triggers incremental builds and interferes with the Node.js version update process. Incremental builds simply don’t start from the very beginning; they always rely on cache. It seems that the dependencies cannot be changed if they are currently being used during an incremental build.

To disable Gatsby Cloud Builds, follow these easy steps:

Log in to your Gatsby Cloud account and navigate to your project dashboard.
Go to Site Settings -> Builds -> Build Features.
Look for the “Enable Cloud Builds” option and disable it.
After disabling Gatsby Cloud Builds, trigger a new build of your Gatsby project on Gatsby Cloud.

And voilà! You should now see that the Node.js version has been successfully updated to the desired version (18.15.0 in this example).

Conclusion

In conclusion, upgrading a Gatsby project from version 4 to version 5 on Gatsby Cloud requires updating the Node.js version. However, when the Node.js version does not change as expected, disabling the Gatsby Cloud Builds option becomes crucial. By following the steps outlined in this article, you can ensure a smooth upgrade process and take advantage of the latest features and improvements in Gatsby version 5.

[the blog]: a little bit of everything

Resolving Node.js Version Error in Gatsby Cloud: Upgrading from Version 4 to 5