jestjs/jest · error · Error

`fsevents` unavailable (this watcher can only be used on Dar

Error message

`fsevents` unavailable (this watcher can only be used on Darwin)

What it means

FSEventsWatcher is the macOS-native file watcher backed by the optional `fsevents` native addon. The module is loaded in a try/catch at module top (FSEventsWatcher.ts:21-25); if require failed (non-Darwin OS or native build missing), the static isSupported() returns false and the constructor throws this error if something still instantiates it directly.

Source

Thrown at packages/jest-haste-map/src/watchers/FSEventsWatcher.ts:58

 * Watches `dir`.
 */
export class FSEventsWatcher extends EventEmitter implements IWatcher {
  readonly root: string;
  readonly ignored: HasteRegExp | undefined;
  readonly glob: Array<string>;
  readonly dot: boolean;
  readonly hasIgnore: boolean;
  readonly doIgnore: (path: string) => boolean;
  readonly fsEventsWatchStopper: () => Promise<void>;
  private readonly _tracked: Set<string>;

  static isSupported(): boolean {
    return fsevents !== null;
  }

  constructor(dir: string, opts: WatcherOptions) {
    if (!fsevents) {
      throw new Error(
        '`fsevents` unavailable (this watcher can only be used on Darwin)',
      );
    }

    super();

    this.dot = opts.dot || false;
    this.ignored = opts.ignored;
    this.glob = [...opts.glob];

    this.hasIgnore = Boolean(opts.ignored);
    this.doIgnore = opts.ignored ? anymatch(opts.ignored) : () => false;

    this.root = path.resolve(dir);
    this.fsEventsWatchStopper = fsevents.watch(
      this.root,
      this.handleEvent.bind(this),
    );

View on GitHub (pinned to f49721c78e)

Solutions

1. Do not instantiate FSEventsWatcher directly; rely on WatcherDriver which checks isSupported() first.
2. On non-macOS, ensure useWatchman:false is not forcing the FSEvents branch — verify your OS and that fsevents is genuinely optional.
3. Reinstall dependencies so the optional fsevents addon is rebuilt: `npm rebuild fsevents` or remove/re-add node_modules.
4. On macOS with a broken fsevents, fall back to NodeWatcher by setting useWatchman:false and ensuring isSupported() returns false (uninstall fsevents).

Example fix

// before — direct instantiation bypasses the platform guard
import {FSEventsWatcher} from 'jest-haste-map/watchers/FSEventsWatcher';
const w = new FSEventsWatcher(dir, opts); // throws on Linux

// after — check support first, fall back to NodeWatcher
import {FSEventsWatcher} from 'jest-haste-map/watchers/FSEventsWatcher';
import NodeWatcher from 'jest-haste-map/watchers/NodeWatcher';
const Backend = FSEventsWatcher.isSupported() ? FSEventsWatcher : NodeWatcher;
const w = new Backend(dir, opts);

import {FSEventsWatcher} from 'jest-haste-map/watchers/FSEventsWatcher';
if (!FSEventsWatcher.isSupported()) {
  throw new Error('FSEventsWatcher not supported on this platform; use NodeWatcher or WatchmanWatcher.');
}

import {FSEventsWatcher} from 'jest-haste-map/watchers/FSEventsWatcher';
function canUseFSEvents(): boolean {
  return FSEventsWatcher.isSupported(); // true only if fsevents loaded (Darwin + addon present)
}

When it happens

Trigger: `new FSEventsWatcher(dir, opts)` is called when the module-level `fsevents` variable is null (line 20), triggering the throw at line 58. In normal Jest flow this path is guarded by FSEventsWatcher.isSupported() in WatcherDriver.start (watchers/index.ts:66), so a direct throw means isSupported() was bypassed or fsevents became unavailable between the check and construction.

Common situations: Running on Linux/Windows where fsevents cannot install; a broken optional-dependency install where fsevents failed to compile; a Docker container on a Mac host that surfaces Darwin but lacks the addon; calling FSEventsWatcher directly from custom tooling without the isSupported guard.

Related errors

• Failed to start watch mode.
• Crawler retry failed: Original error: ${retryError.message
• jest-haste-map: the `ignorePattern` option must be a RegExp
• jest-haste-map: enableSymlinks config option was set, but is
• Duplicated files or mocks. Please check the console for more

AI-assisted analysis of jestjs/jest@f49721c78e (2026-08-03). Data as JSON: /data/errors/82518dd103d48257.json. Report an issue: GitHub.