Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

npm start runs, but the browser does not refresh when you save a file

ErrorDevelopment server of create-react-app does not auto refresh

Short answer

The watcher behind npm start is not seeing your edit. It only watches files that the entrypoint imports, it can be blinded by editor safe-write, odd paths or a low watcher limit, and it needs polling inside a VM or shared folder. Check each in that order; most cases end with one setting.

  • Applies to react-scripts 5, Node.js 22, Linux, macOS, Windows
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Edit a file you know the app uses (for example src/App.js), save it, and watch the terminal. If a rebuild line appears, the watcher works and the problem is in the browser or in what that file is connected to.

    npm start
  2. 2Match what you see, then jump to its fix

    1. 1Edits to one file are ignored, edits to others reload fineThe file is not imported by the entrypointFix
    2. 2Nothing reloads from Vim or IntelliJ, or the project sits in Dropbox or a path with parenthesesThe editor's safe write, the project path or the file name case breaks the watcherFix
    3. 3Watch errors such as ENOSPC in the terminal on LinuxThe system allows too few file watchersFix
    4. 4The project is in a virtual machine or on a shared folderThe code runs inside a VM, so file events never arriveFix

What does the error look like?

  • Development server of create-react-app does not auto refresh
  • Saving a file does nothing while npm start is running

Cause 1 of 4

The file is not imported by the entrypoint

1Check

Webpack reloads only files that the entrypoint (src/index.js) imports, directly or through other files. A file nothing imports is never watched.

grep -rn "from './MyComponent'" src/

2Fix

Import the file from a component that the entrypoint reaches.

import MyComponent from './MyComponent';

3Verify

Save the file; the terminal shows a recompile and the page updates.

npm start

Confirmed by create-react-app.dev

Did this fix it?

Cause 2 of 4

The editor's safe write, the project path or the file name case breaks the watcher

1Check

The troubleshooting guide lists known triggers: the safe write feature of editors such as Vim and IntelliJ, a project inside a Dropbox folder, parentheses in the project path, and a file renamed by case only (restart the watcher then).

pwd

2Fix

Turn off safe write in the editor, move the project out of Dropbox or out of a path containing parentheses, and restart npm start after a case-only rename.

mv ~/Dropbox/my-app ~/projects/my-app

3Verify

Edit and save a component; the dev server recompiles.

cd ~/projects/my-app && npm start

Confirmed by create-react-app.dev

Did this fix it?

Cause 3 of 4

The system allows too few file watchers

1Check

On Linux and macOS the number of watched files is limited by the system; large node_modules trees can use it all.

cat /proc/sys/fs/inotify/max_user_watches

2Fix

Raise the limit. This is the command the Create React App docs give for Debian and Red Hat style systems.

echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p

3Verify

Restart npm start; the watch error is gone and edits reload.

npm start

Confirmed by create-react-app.dev

Did this fix it?

Cause 4 of 4

The code runs inside a VM, so file events never arrive

1Check

Inside a VM the watcher may not receive change events from the host's file system. Polling mode is meant for this case.

cat .env 2>/dev/null

2Fix

Add the polling flag to a .env file in the project root and restart the server.

echo CHOKIDAR_USEPOLLING=true >> .env

3Verify

Edit a file on the host; the dev server recompiles inside the VM.

npm start

Confirmed by create-react-app.dev

Did this fix it?

How do I stop it coming back?

  • Keep projects on the local disk of the machine that runs the dev server.
  • Keep paths short and free of parentheses.
  • Remember that the watcher follows the import graph from src/index.js.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.