Troubleshooting Common Errors
As you encounter errors while developing with Gatsby, it is likely you’ll run into something that other users have already stumbled upon. Some errors may require fixes to Gatsby’s core processes, these are best filed as issues. Many errors you encounter will mean adjusting how you’ve configured a plugin or API in your site.
This guide is meant as a reference for common errors that have tripped up other Gatsby users.
Running a site in
gatsby develop will set up a server locally that enables features like hot-module replacement. Gatsby keeps a cache of data and rendered assets in the
.cache folder at the root of a Gatsby site so that it doesn’t have to repeat work processing optimized resources. If you see errors about not being able to find a resource in the cache it may be enough to clear your cache and restart your server. You can clear Gatsby’s cache by running:
This will delete the
.cache folder, as well as the
public folder for you. Running
gatsby develop will recreate the cache and process all resources again.
You may also want to refer to the dedicated guide on Debugging Cache Issues.
For additional discussion on caching and persistence issues, refer to the umbrella issue.
Plugins extend Gatsby’s functionality, because they introduce new behavior it’s possible that an installed plugin introduces errors.
If you encounter a webpack error that says
Generating SSR bundle failed after installing a plugin and trying to run
gatsby develop or
gatsby build, it’s possible you haven’t yet installed all the packages you need.
For some plugins like emotion, styled-components, or SASS, it won’t be enough to only install the plugin, you also need to install libraries they rely on. The official installation instructions should guide you to install all needed libraries when you install the plugin, but some tutorials or blog posts you find at other sources may not.
Here are some examples of plugins that require you to install more than just the plugin:
Rather than packaging up the other dependent libraries alongside these plugins, they can stay smaller in size when they are published and are able to rely on alternative implementations. One example is
gatsby-plugin-sass that can use either the Node.js or Dart implementations of SASS.
To resolve these errors, identify the packages that haven’t been installed, the error message might look like this:
This error is a result of Gatsby having failed to find
gatsby-plugin-emotion has been installed and added to the
gatsby-config, without installing the emotion library. Install it like this:
@emotion/core with the name of the library that is missing. Installing the plugin and any necessary libraries as well as adding the plugin to your
gatsby-config should resolve this error.
The following errors are related to styles in your site, using CSS, preprocessors, or CSS-in-JSS solutions.
A common problem that trips up users that install and begin to use styled-components or emotion is not including the related plugin in the config. Because
gatsby develop doesn’t run server-side rendering, the build may look different if the plugin is not included to tell Gatsby to server-side render the styles for the CSS-in-JS solution being used.
gatsby-plugin-styled-components (in the case of styled-components) or
gatsby-plugin-emotion (in the case of emotion) to
gatsby-config.js will inform Gatsby to process the styles server-side so they display correctly in the final build.
Gatsby’s GraphQL data layer provides access to build time data, there are sometimes errors you may encounter while implementing plugins that are sourcing data or adding nodes to the schema yourself.
If the data you are requesting in a GraphQL query differs from what has been sourced in the GraphQL schema you might encounter an error like
Unknown field 'A' on type 'B'. As the error suggests, a field you are asking for is not defined under the type that is listed. If your site is still building okay, you can open up
http://localhost:8000/___graphql and examine your schema, which includes the definition of what fields are included on the type provided by the error. This can help you identify what fields aren’t being created and locate where those fields should be created, whether by a plugin or in your code.
If the error is describing an
Unknown field 'X' on type 'Query', the content type you are trying to source is likely not processing correctly. The
Query type represents the top-level root queries that are included in the GraphQL schema. Source plugins will often create root nodes that you can query like
mdx (created by
gatsby-plugin-mdx) or for a collection of root nodes like
allFile (created by
Some ideas for debugging these errors include verifying the following:
- if you are using a transformer plugin (like
gatsby-transformer-yaml), the data you need is pulled in using a source plugin (like
- the structure of your content being sourced matches your GraphQL schema as well as the way you are querying the data
Comparing your GraphQL query to your site’s schema in
http://localhost:8000/___graphql and whatever plugin or code you are using to source data is a great way to find these errors as they should all express the data in the same shape.
- neither any source plugins you are using nor your own implementation of the
sourceNodesAPI are misconfigured
Gatsby’s image processing is broken up into different packages which need to work together to source images and transform them into different optimized versions. You might run into these errors getting them to play together nicely.
This errror message
Field "image" must not have a selection since type "String" has no subfields. comes up when a GraphQL query is trying to query a field for subfields, but none exist. This generally happens when plugins that are used together are added in the
gatsby-config in the wrong order, or haven’t been added at all.
The query is trying to access fields that don’t exist because they weren’t set up at build time. In the following code, a query is looking to find the subfield
childImageSharp of the
image field, like the error states. The problematic GraphQL schema looks like this:
And the expected GraphQL schema looks this:
In the first code example, the
image field was not transformed (modified) by a plugin to add subfields, so it would only return a string.
gatsby-transformer-sharp can be included before other plugins that would manipulate or create image nodes (like
gatsby-source-contentful) to ensure that they are present before Gatsby tries to modify them and add the needed fields like
You can read more about how images are added to the GraphQL schema in the guide on processing external images.
Another possibility that could cause this issue is from empty strings used for image paths somewhere in your site. If this is the case, when Gatsby constructs a GraphQL schema it may infer the wrong type because the empty string doesn’t look like a file path.
If you see an error message in the console when installing dependencies that look related to sharp like
gyp ERR! build error and
npm ERR! Failed at the firstname.lastname@example.org install script, they can often be resolved by deleting the
node_nodules folder in the root of your project and installing dependencies again:
The version of Node.js that’s used to install sharp needs to match the version of Node.js that is run, so clearing
node_modules and reinstalling often resolves the problem.
For more discussion around problems with sharp installation and image processing, refer to this issue.
Incompatible library version: sharp.node requires version X or later, but Y provides version Z means that there are multiple incompatible versions of the
sharp package installed in
node_modules. Your error may look something like this:
To fix this, you’ll need to update all Gatsby plugins in the current project that depend on the
sharp package. Here’s a list of official plugins that you might need to update in case your project uses them:
To update these packages, run:
If updating these doesn’t fix the issue, your project probably uses other plugins from the community that depend on a different version of
sharp. Try running
npm list sharp or
yarn why sharp to see all packages in the current project that use
sharp and try updating them as well.
The process of building your site varies slightly from the development process. Some errors can arise when you build your site if you include references to the browser, though almost all problems should be caught by error messages in
For more information on common problems while building your site, refer to the Debugging HTML Builds guide.
You may encounter an error like
Error: ReferenceError: window is not defined that you didn’t see in development if you reference browser globals like
document in your code. Because the build is not running in a browser, it will not have access to a browser, which is why objects like
window will not be defined.
Exact steps for fixing this issue can be found on in the Debugging HTML Builds guide in the section on checking if
window is defined.
If you are seeing an error like:
The build is failing to find the file at
../..SomeFile.svg. This can be frustrating if your site works when you when run it locally with
gatsby develop, and even works when you run
gatsby build and
gatsby serve locally. A likely problem is that the operating system you are running locally is different than the one where your site is deployed. Oftentimes your deployment target is running some distribution and flavor of Linux.
The most common culprit to prompt this issue is with filepaths having mixed capitalization. In the example above, check to make sure that the file is actually named
SomeFile.svg and not something different like
somefile.svg. Some operating systems will pick up on this discrepancy for you and find the image without any problems. Your deployment environment may not.
Checking the capitalization of files output in your build logs and redeploying is the best next step.
You may have encountered a system limit on the number of files you can monitor.
To fix it, increase your system’s file watchers limit (which is the number of processes that check for changes to files in your site while it’s running) with the following command:
You may be able to find more information for your circumstances in the GitHub issue corresponding to this error.