Common React Setup Errors and How to Fix Them

Most React setup errors happen before your code runs: missing dependencies, an old Node version, or JSX that is not being compiled. Each has a clear symptom and a quick fix, and this guide walks through the ones beginners hit most.

When a fix mentions Node, use the guide on setting up Node.js for React for the full install steps.

Module not found: cannot resolve react

The error looks like Cannot find module 'react' or a build message naming a package. The cause is usually that dependencies were never installed.

Fix it by running this in the project folder:

bash

npm install

If that fails, delete the node_modules folder and run npm install again. Keep the lockfile, since it pins the versions the project was tested with, and regenerate it only when the install still fails.

Node command not found or too old

A node: command not found error means Node is not installed or not on your PATH. A version warning means Node is older than the project requires.

Check your version:

bash

node --version

If the command fails, install Node. If the version is too old, upgrade to Node 20.19 or newer, or 22.12 or newer, which is what current Vite projects require. Installing the current LTS release covers both.

Unexpected token: JSX is not compiling

A syntax error pointing at a JSX tag means the build tool is not transforming JSX. This happens when a component file has the wrong extension or the project has no JSX plugin.

Make sure component files end in .jsx or .tsx, and that the project was created with a React template. If you are unsure, create a React app with Vite and copy your component into it.

Invalid hook call

The Invalid hook call error means a hook like useState was called outside a component or a custom hook, or called conditionally.

Hooks must run at the top level of a component:

App.jsx

import { useState } from "react";
 
function Counter() {
  const [count, setCount] = useState(0);
 
  return <button>Count: {count}</button>;
}

Do not place a hook inside an if statement or a loop. Move it to the top of the function instead.

The same error also appears when a project ends up with two copies of React, which happens with linked packages or a mismatched dependency. List them with:

bash

npm ls react

If more than one version is printed, the react import in your code and the one inside react-dom resolve to different modules, and hooks break. Align the versions so a single copy remains.

Port already in use

A port already in use error means another process is using the dev server port, usually 5173.

Stop the other process, or start on a different port:

bash

npm run dev -- --port 5174

The dev server prints the new URL, and you can open it directly.

The page renders blank

A blank page usually means React never attached to the page. The most common cause is a missing or mismatched root element.

Confirm index.html has an element with the id your main file looks for. In a Vite project that is a div with id root.

What to learn next

These fixes cover the errors you meet in the first days. Once the project runs, the guide on your first React component is a good next step.