Gatsby: Error messages - contribute to improvements!

[shannonbux]

The Great Error Message Voyage

Summary

Great error messages are part of helping users recognize and recover from errors. This project summarizes how to make a list of errors and then improve the errors.

1. How to make a complete list of errors

A) When you find an error that is not yet on the list below, create an issue using this template.
B) Add your issue to the "List of errors" below and link to it.

List of errors

• [x] [insert link to issue describing the error here] [insert category here - GraphQL, Webpack, or "unknown"] [insert grade here]

2. How to improve errors

A) Choose an error from the checklist above
B) Look at the grade for the error
C) Open a PR (linked to the corresponding issue) that improves one error message by at least one grade level (mention this issue #15019 in your issue). Take an error from 1 to 2, for example.

Example

Here is an example of an error message that was taken from level 1 to level 3.

[insert issue describing a recently improved error]
[insert PR that resolved the issue above. PR should show a screenshot of what the new error message looks like in the CLI]

Motivation

The faster that users can recognize, diagnose, and recover from an error, the faster users can build a super awesome, fast Gatsby project!

Key for Grades

This is what the grades mean:
0: Silent error
1: An error is thrown, and the message is missing one or more of the following: id, category, name, description, prompt for fix.
2: Error message with id, category, name, and description
3: Error message with id, category, name, and description + prompt for fix (can be URL to docs page, code example, example site, suggestion, etc)
4: Error message with id, category, name, and description + prompt for fix + adaptive prompting

[nwthomas]

I want to be involved with this as I'm just coming off writing custom thrown errors for React-Conflux.

As this is my first Gatsby issue, I'm willing to do whatever is needed. I'd love to take on some of the first errors posted here and get my feet wet.

[chrismgonzalez]

I've got an error message that I would've been able to solve in 2 seconds had I had an appropriate prompt. Will submit something soon.

[m-allanson]

Note that For PRs updating these error we'll need to wait for https://github.com/gatsbyjs/gatsby/pull/14904 to be merged. Until that happens please go ahead and create issues that identify specific errors!

Once #14904 is merged, this issue should be updated with more detailed instructions on how to improve a specific error.

[KyleAMathews]

We don't capture GraphQL errors from the internal graphql function used in gatsby-node.js apis

https://github.com/gatsbyjs/gatsby/issues/15212

[KyleAMathews]

New PR to make errors loading gatsby-config.js structured https://github.com/gatsbyjs/gatsby/pull/15244

[m-allanson]

We could improve the error from running gatsby new for a starter that doesn't exist. Steps to reproduce:

• Run gatsby new my-blog gatsby-starter-blog-theme (note the theme name should be a full url, or in the form github-organistion/repo-name)

• See this error:

 ERROR

starter gatsby-starter-blog-theme doesn't exist



  Error: starter gatsby-starter-blog-theme doesn't exist

  - init-starter.js:201
    [lib]/[gatsby-cli]/lib/init-starter.js:201:13

  - Generator.next

Improvements:

• remove the stack trace
• check format of the theme name (not a valid url? or missing org / repo separator if not a url?)
• list location that's being checked Check that a starter exists at https://github.com/<starter-name>.
• add autosuggest options for official themes? Did you mean gatsbyjs/gatsby-starter-blog-theme

[LekoArts]

Some more error ideas (which I wrote down while we were in Berlin):

• Errors around environment variables
  
  
  
  • typos
  
  
  • missing env variable
  
  
  • trying to access an env variable in the browser but not prefixing it with GATSBY_
  
  
• Variables in StaticQuery
• Same names for GraphQL queries
• Deleted/non-existent file (and trying to access those)
• String interpolations in the graphql function
  
  
  
  • People sometimes try to use variables this way in GraphQL queries or try to split queries into re-usable parts
  
  
• Any error around external packages that use "window" or errors around (local) plugins
• GraphQL fragments
  
  
  
  • e.g. a custom fragment is defined in a file but wrongly imported or wrongly used
  
  

---

This list isn't going into any details yet so for people who want to tackle those:

Try to generate errors for these scenarios and see which grade they are. For example some errors around GraphQL fragments were already improved (errors around wrong gatsby-image fragments), but we didn't test everything. Maybe some of these things are already fixed 😆

[mats-codes]

Is there anything left here, that I could help with? I'd be very happy to do so :)

[sidharthachatterjee]

Let's go ahead and close this since we now have several independent issues for specific error cases that could be improved. If there are more than you think of, please open an issue!

Thank you to all of you! 💜