docs: guide on troubleshooting common errors

docs/docs/troubleshooting-common-errors.md

@@ -8,7 +8,7 @@ This guide is meant as a reference for common errors that have tripped up other
 
 ## Problems with the cache
 
-Running a site in `gatsby develop` will set up a server locally that enables features like [hot-module replacement](/glossary#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;
+Running a site in `gatsby develop` will set up a server locally that enables features like [hot-module replacement](/docs/glossary#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:
 
 ```shell
 gatsby clean
@@ -18,6 +18,8 @@ This will delete the `.cache` folder, as well as the `public` folder for you. Ru
 
 You may also want to refer to the dedicated guide on [Debugging Cache Issues](/docs/debugging-cache-issues/).
 
+> For additional discussion on caching and persistence issues, refer to the [umbrella issue](https://github.com/gatsbyjs/gatsby/issues/11747).
+
 ## Errors with common plugin configurations
 
 Plugins [extend Gatsby's functionality](/docs/what-is-a-plugin/), because they introduce new behavior it's possible that an installed plugin introduces errors.
@@ -26,13 +28,14 @@ Plugins [extend Gatsby's functionality](/docs/what-is-a-plugin/), because they i
 
 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 styled-components, emotion, 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.
+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:
 
 - [gatsby-plugin-emotion](/packages/gatsby-plugin-emotion/): `@emotion/core`, and `@emotion/styled`
 - [gatsby-plugin-styled-components](/packages/gatsby-plugin-styled-components/): `styled-components`, and `babel-plugin-styled-components`
 - [gatsby-plugin-sass](/packages/gatsby-plugin-sass/): `node-sass`, or `dart-sass`
+- [gatsby-plugin-material-ui](/packages/gatsby-plugin-material-ui/): `@material-ui/styles`
 - [gatsby-image](/packages/gatsby-image/): `gatsby-transformer-sharp`, and `gatsby-plugin-sharp`
 
 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.
@@ -52,13 +55,13 @@ Can't resolve '@emotion/core' in '/Users/you/tmp/gatsby-site/.cache' // highligh
 File: .cache/develop-static-entry.js
 ```
 
-This error is a result of Gatsby having failing to find `@emotion/core` because `gatsby-plugin-emotion` has been installed and added to the `gatsby-config`, without installing the emotion library. Install it like this:
+This error is a result of Gatsby having failed to find `@emotion/core` because `gatsby-plugin-emotion` has been installed and added to the `gatsby-config`, without installing the emotion library. Install it like this:
 
 ```shell
 npm install --save @emotion/core
 ```
 
-Or replace `@emotion/core` with the name of the library that is missing. With the plugin installed, any necessary libraries installed, and the plugin added to your `gatsby-config`, it should resolve this error.
+Or replace `@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.
 
 ## Errors in styling
 
@@ -76,13 +79,13 @@ Gatsby's GraphQL data layer provides access to build time data, there are someti
 
 ### Unknown field 'A' on type 'B'
 
-If the data you are requesting in a GraphQL query differs from what has been [sourced](/docs/content-and-data/) in the GraphQL schema you might encounter an error like `Unknown field 'A' on type 'B'`. Like 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 `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 data you are requesting in a GraphQL query differs from what has been [sourced](/docs/content-and-data/) 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 `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 `gatsby-source-filesystem`).
 
-Some ideas for debugging these errors is to verify the following:
+Some ideas for debugging these errors include verifying the following:
 
-- you are using a transformer plugin (like `gatsby-transformer-yaml`) the data you need is pulled in using a source plugin (like `gatsby-source-filesystem`)
+- if you are using a transformer plugin (like `gatsby-transformer-yaml`), the data you need is pulled in using a source plugin (like `gatsby-source-filesystem`)
 
 ```javascript:title=gatsby-config.js
 {
@@ -102,7 +105,7 @@ Some ideas for debugging these errors is to verify the following:
 
 Comparing your GraphQL query to your site's schema in [GraphiQL at `localhost:8000/___graphql`](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.
 
-- a source plugin you are using, or your own implementation of the [`sourceNodes` API](/docs/node-apis/#sourceNodes) isn't misconfigured
+- neither any source plugins you are using nor your own implementation of the [`sourceNodes` API](/docs/node-apis/#sourceNodes) are misconfigured
 
 ## Errors using gatsby-image and sharp
 
@@ -142,9 +145,11 @@ allMdx {
 }
 ```
 
-In the first code example, the `image` field was not modified (using Gatsby terminology, transformed) by a plugin to add subfields, so it would only return a string. `gatsby-plugin-sharp` and `gatsby-transformer-sharp` can be included before other plugins that would manipulate or create image nodes (like `gatsby-source-filesystem` or `gatsby-source-contentful`) to ensure that they are present before Gatsby tries to modify them and add the needed fields like `childImageSharp`.
+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-plugin-sharp` and `gatsby-transformer-sharp` can be included before other plugins that would manipulate or create image nodes (like `gatsby-source-filesystem` or `gatsby-source-contentful`) to ensure that they are present before Gatsby tries to modify them and add the needed fields like `childImageSharp`.
+
+You can read more about how images are added to the GraphQL schema in the guide on [processing external images](/docs/preprocessing-external-images/).
 
-Another possibility is that empty strings are used for image paths somewhere in your site, and when Gatsby constructs a GraphQL schema it [infers](/docs/glossary#inference) the wrong type because the empty string doesn't look like a path.
+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](/docs/glossary#inference) the wrong type because the empty string doesn't look like a file path.
 
 ### Problems installing `sharp` with `gatsby-plugin-sharp` - gyp ERR! build error
 
@@ -162,6 +167,8 @@ npm install
 
 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](https://github.com/gatsbyjs/gatsby/issues/10841).
+
 ### Incompatible library version: sharp.node requires version X or later, but Y provides version Z
 
 The error `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:
@@ -192,10 +199,16 @@ If updating these doesn't fix the issue, your project probably uses other plugin
 
 ## Errors building and deploying
 
-The process of building your site [varies slightly from the development process](/docs/overview-of-the-gatsby-build-process/). Some errors can arise when you build your site if
+The process of building your site [varies slightly from the development process](/docs/overview-of-the-gatsby-build-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 `develop` mode.
 
 For more information on common problems while building your site, refer to the [Debugging HTML Builds](/docs/debugging-html-builds/) guide.
 
+### Error: ReferenceError: window is not defined when running `gatsby build`
+
+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 `window` or `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](/docs/debugging-html-builds/#how-to-check-if-window-is-defined).
+
 ### Build problems from Field 'browser' doesn't contain a valid alias configuration
 
 If you are seeing an error like:
@@ -211,9 +224,3 @@ The build is failing to find the file at `../..SomeFile.svg`. This can be frustr
 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` or `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.
-
-### Error: ReferenceError: window is not defined when running `gatsby build`
-
-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 `window` or `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](/docs/debugging-html-builds/#how-to-check-if-window-is-defined).