dev server on linux breaks when a watched file is edited unless watchman is installed

[donhatch]

🐛 bug report

I had a frustrating time trying to follow the basic parcel webapp "Getting Started" instructions on linux: the dev server breaks (and has to be restarted) whenever I edit and save any of the source files.
I looked for a while on the web, searching for the text from the error message, without success.

I discovered much later that, if I install watchman (on my linux system) and restart the dev server, it starts working fine.
(This doc page indicates that, on linux, parcel uses watchman if installed, falling back to an internal inotify-based watcher implementation otherwise. So the problem is evidently in the internal inotify-based watcher.)

There is also documentation describing editor-configuration-based workarounds that can be used in some editors, here.
But that's not a solution:

• it's discoverable only if already known (not when someone is trying to follow the "Get Started" instructions)
• it's intrusive, lowering the quality of my editor configurations
• it's shouldn't be necessary: watchman-based watching works without it, vite's dev server works without it.

To Reproduce:

First make sure watchman is not installed:

apt list --installed watchman
# should produce no output

Following the webapp quickstart instructions here:

npm create parcel vanilla my-parcel-app
# and then, as it says...
cd my-parcel-app
npm start

and point a browser to the URL it shows: http://localhost:1234.
It successfully brings up the app as expected, with no errors in the dev js console:

Now edit and save src/index.html.
Both the dev server and the app page instantly change to showing this:

🚨 Build failed.

@parcel/core: src/index.html does not exist.

  /home/donhatch/backed_up/gitrepos/mine/parcel_play/my-parcel-app/package.json:5:13
    4 |   "version": "0.0.0",
  > 5 |   "source": "src/index.html",
  >   |             ^^^^^^^^^^^^^^^^
    6 |   "scripts": {
    7 |     "start": "parcel",

  💡 Did you mean './src/index.html~'?
  💡 Did you mean './dist/index.html'?

Reloading the page in the browser doesn't help; evidently the server must be restarted.

I can then make it work by installing watchman:

sudo apt install watchman

and restarting the parcel dev server; then it works fine.
If I then uninstall watchman:

sudo apt remove watchman

and restart the parcel dev server, it goes back to breaking on first file change.

🎛 Configuration (.babelrc, package.json, cli command)

This is what the above npm create parcel vanilla my-parcel-app command produced.

{
  "name": "parcel-vanilla-starter",
  "private": true,
  "version": "0.0.0",
  "source": "src/index.html",
  "scripts": {
    "start": "parcel",
    "build": "parcel build"
  },
  "dependencies": {},
  "devDependencies": {
    "parcel": "^2.14.0"
  }
}

🔦 Context

Just trying to follow the "get started" instructions.

🌍 Your Environment

Software	Version(s)
Parcel	2.16.4
Node	20.19.4
npm/Yarn	9.2.0
Operating System	ubuntu linux 25.10