Node "Cannot find module 'fsevents'" (optional, mac-only) in CI

fsevents is a macOS-only optional dependency used for fast file watching. On a Linux runner it is intentionally not installed - so a hard "Cannot find module fsevents" usually means code required it unconditionally, masking the real issue.

What this error means

A Linux CI job logs "Cannot find module 'fsevents'". Often it is a harmless optional-dep warning, but if it throws, something is requiring fsevents directly instead of treating it as optional.

node

Error: Cannot find module 'fsevents'
Require stack:
- /work/repo/node_modules/chokidar/lib/fsevents-handler.js

Common causes

fsevents required unconditionally

Code or a tool does a hard require("fsevents") instead of an optional try/catch, so Linux (where it is absent by design) throws.

A corrupted lockfile forcing fsevents

A lockfile that lists fsevents as a non-optional dependency makes npm attempt to load it everywhere.

How to fix it

Treat fsevents as optional

Let the watcher fall back to the Linux backend; do not require fsevents directly.

source

let fsevents;
try { fsevents = require('fsevents'); } catch { /* not on this platform */ }

Keep optional deps optional in the lockfile

Regenerate the lockfile so fsevents is recorded as an optional, OS-scoped dependency.

Confirm fsevents appears under optionalDependencies, not dependencies.
Reinstall with optional deps enabled.
Verify chokidar/rollup load without throwing on Linux.

How to prevent it

Never require fsevents unconditionally; guard it in a try/catch.
Keep fsevents as an OS-scoped optional dependency.
Verify watchers fall back to the Linux backend in CI.