Error following Tutorial when installing gatsby-plugin-mdx

[conradoplg]

Preliminary Checks

• This issue is not a duplicate. Before opening a new issue, please search existing issues: https://github.com/gatsbyjs/gatsby/issues
• This issue is not a question, feature request, RFC, or anything other than a bug report directly related to Gatsby. Please post those things in GitHub Discussions: https://github.com/gatsbyjs/gatsby/discussions

Description

When following the tutorial, npm install gatsby-plugin-mdx @mdx-js/mdx@v1 @mdx-js/react@v1 fails.

Reproduction Link

https://www.gatsbyjs.com/docs/tutorial/part-5/

Steps to Reproduce

1. Follow the tutorial until Part 5
2. Installing gatsby-plugin-mdx fails
   ...

Expected Result

Install should work

Actual Result

Fails with (edited):

npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR! 
npm ERR! While resolving: <package>@1.0.0
npm ERR! Found: [email protected]
npm ERR! node_modules/react
npm ERR!   react@"^18.1.0" from the root project
npm ERR!   peer react@"^16.9.0 || ^17.0.0 || ^18.0.0" from [email protected]
npm ERR!   node_modules/gatsby-plugin-mdx
npm ERR!     gatsby-plugin-mdx@"*" from the root project
npm ERR! 
npm ERR! Could not resolve dependency:
npm ERR! peer react@"^16.13.1 || ^17.0.0" from @mdx-js/[email protected]
npm ERR! node_modules/@mdx-js/react
npm ERR!   @mdx-js/react@"v1" from the root project
npm ERR!   peer @mdx-js/react@"^1.0.0" from [email protected]
npm ERR!   node_modules/gatsby-plugin-mdx
npm ERR!     gatsby-plugin-mdx@"*" from the root project
npm ERR! 
npm ERR! Fix the upstream dependency conflict, or retry
npm ERR! this command with --force, or --legacy-peer-deps
npm ERR! to accept an incorrect (and potentially broken) dependency resolution.
npm ERR! 

It worked after I manually changed from

    "react": "^18.1.0",
    "react-dom": "^18.1.0"

to

    "react": "^17.0.0",
    "react-dom": "^17.0.0"

Environment

System:
    OS: Linux 5.15 Ubuntu 20.04.4 LTS (Focal Fossa)
    CPU: (24) x64 AMD Ryzen 9 5900X 12-Core Processor
    Shell: 5.0.17 - /bin/bash
  Binaries:
    Node: 16.16.0 - /usr/bin/node
    Yarn: 1.22.15 - /usr/bin/yarn
    npm: 8.11.0 - /usr/bin/npm
  Languages:
    Python: 3.8.10 - /usr/bin/python
  Browsers:
    Chrome: 103.0.5060.114
    Firefox: 102.0
  npmPackages:
    gatsby: ^4.18.2 => 4.18.2 
    gatsby-plugin-image: ^2.18.1 => 2.18.1 
    gatsby-plugin-mdx: ^3.18.1 => 3.18.1 
    gatsby-plugin-sharp: ^4.18.1 => 4.18.1 
    gatsby-source-filesystem: ^4.18.1 => 4.18.1 
  npmGlobalPackages:
    gatsby-cli: 4.18.1

Config Flags

No response

[LekoArts]

You can workaround this issue by using npm install --legacy-peer-deps

[neogmanish99]

I'm facing the same issue 😶

[tkozuch]

doesn't this risk problems when working with the app later on?

[dgpalmer]

still an issue in 2025, absolutely terrible out of the box experience for gatsby, npm errors from a fresh npm init gatsby is diabolical