Troubleshooting

Run into some problems running the workshops on your machine? This page lists the solutions to common problems.

Dependency conflicts during NPM install

When you run npm install, you may get an error that looks something like this:

While resolving: some-react-library@2.0.0

Could not resolve dependency:
peer react@"^17.0.0 || ^18.0.0" from some-react-library@2.0.0

This happens because each NPM package can specify compatible versions of their dependencies. In this example, some-react-library requires React 17 or 18, but the project is running React 19.

In theory, we don’t want to install incompatible versions, but in practice, what winds up happening is that many packages don’t update their accepted ranges when new versions of their dependencies come out, even though everything still works great.

I have made sure that there are no actual compatibility problems with the dependencies used in these workshops. So this is a false alarm.

If you’re only seeing a warning, it’s safe to ignore it. Certain versions of NPM, however, will error out when they encounter this issue.To solve this problem, add the following flag to your npm install command:

npm install --legacy-peer-deps

This tells NPM that it’s OK to proceed even with mismatched dependency versions.

structuredClone is not defined

When running a dev server, you may encounter the following error:

error when starting dev server:
ReferenceError: structuredClone is not defined
    at deepClone (file:///.../node/chunks/dep-yUJfKD1i.js:10245:5)
    at file:///.../node/chunks/dep-yUJfKD1i.js:10232:29
    at Array.map (<anonymous>)

This happens when your version of Node is too old. These workshops require Node 18 or newer.

To solve this problem, you’ll need to install a newer version of Node. I recommend using the current LTS version. LTS stands for “Long Term Support”, and these versions tend to be the most reliable.

Digital Envelope Routines

On older versions of our workshops, it was common to encounter the following error:

Error: error:0308010C:digital envelope routines::unsupported
at new Hash (node:internal/crypto/hash:67:19)
at Object.createHash (node:crypto:130:10)

If you’re using the most recent version of the workshop, you shouldn’t run into this issue. It was specific to create-react-app, and in December 2024, I updated all workshops to use Vite instead.

That said, if you want to solve this problem, there are two options:

1. Use an older version of Node.js

This issue is specific to Node 17+. If you can switch to Node 16 or earlier, this issue goes away.

As mentioned above, a version manager like NVM (opens in new tab) can be really useful here. That way, we can switch to Node 16 just for the problematic project.

2. Update the `package.json` file

Instead of switching to an older version of Node, we can also instruct Node to use an older, compatible version of one of its internal libraries.

Update the project's package.json as follows:

{
  // From this:
  "scripts": {
    "start": "react-scripts start",
    "build": "react-scripts build",
    "test": "react-scripts test",
    "eject": "react-scripts eject"
  },

  // ...To this:
  "scripts": {
    "start": "NODE_OPTIONS=--openssl-legacy-provider react-scripts start",
    "build": "react-scripts build",
    "test": "react-scripts test",
    "eject": "react-scripts eject"
  }
}

Essentially, we need to add NODE_OPTIONS=--openssl-legacy-provider before the stuff in the start script.

If you're a Windows user, depending on your setup, you might need to tweak this change to:

{
  "scripts": {
    "start": "set NODE_OPTIONS=--openssl-legacy-provider && react-scripts start",
    "build": "react-scripts build",
    "test": "react-scripts test",
    "eject": "react-scripts eject"
  }
}

Note that this flag only works if you're using Node 17 or newer. If you try to add this flag while running Node 16, you'll get an error.