{"id":"82518dd103d48257","repo":"jestjs/jest","slug":"fsevents-unavailable-this-watcher-can-only-be-u","errorCode":null,"errorMessage":"`fsevents` unavailable (this watcher can only be used on Darwin)","messagePattern":"`fsevents` unavailable \\(this watcher can only be used on Darwin\\)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/jest-haste-map/src/watchers/FSEventsWatcher.ts","lineNumber":58,"sourceCode":" * Watches `dir`.\n */\nexport class FSEventsWatcher extends EventEmitter implements IWatcher {\n  readonly root: string;\n  readonly ignored: HasteRegExp | undefined;\n  readonly glob: Array<string>;\n  readonly dot: boolean;\n  readonly hasIgnore: boolean;\n  readonly doIgnore: (path: string) => boolean;\n  readonly fsEventsWatchStopper: () => Promise<void>;\n  private readonly _tracked: Set<string>;\n\n  static isSupported(): boolean {\n    return fsevents !== null;\n  }\n\n  constructor(dir: string, opts: WatcherOptions) {\n    if (!fsevents) {\n      throw new Error(\n        '`fsevents` unavailable (this watcher can only be used on Darwin)',\n      );\n    }\n\n    super();\n\n    this.dot = opts.dot || false;\n    this.ignored = opts.ignored;\n    this.glob = [...opts.glob];\n\n    this.hasIgnore = Boolean(opts.ignored);\n    this.doIgnore = opts.ignored ? anymatch(opts.ignored) : () => false;\n\n    this.root = path.resolve(dir);\n    this.fsEventsWatchStopper = fsevents.watch(\n      this.root,\n      this.handleEvent.bind(this),\n    );","sourceCodeStart":40,"sourceCodeEnd":76,"githubUrl":"https://github.com/jestjs/jest/blob/f49721c78e195558b40913977c9230f5b7f559d8/packages/jest-haste-map/src/watchers/FSEventsWatcher.ts#L40-L76","documentation":"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.","triggerScenarios":"`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.","commonSituations":"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.","solutions":["Do not instantiate FSEventsWatcher directly; rely on WatcherDriver which checks isSupported() first.","On non-macOS, ensure useWatchman:false is not forcing the FSEvents branch — verify your OS and that fsevents is genuinely optional.","Reinstall dependencies so the optional fsevents addon is rebuilt: `npm rebuild fsevents` or remove/re-add node_modules.","On macOS with a broken fsevents, fall back to NodeWatcher by setting useWatchman:false and ensuring isSupported() returns false (uninstall fsevents)."],"exampleFix":"// before — direct instantiation bypasses the platform guard\nimport {FSEventsWatcher} from 'jest-haste-map/watchers/FSEventsWatcher';\nconst w = new FSEventsWatcher(dir, opts); // throws on Linux\n\n// after — check support first, fall back to NodeWatcher\nimport {FSEventsWatcher} from 'jest-haste-map/watchers/FSEventsWatcher';\nimport NodeWatcher from 'jest-haste-map/watchers/NodeWatcher';\nconst Backend = FSEventsWatcher.isSupported() ? FSEventsWatcher : NodeWatcher;\nconst w = new Backend(dir, opts);","handlingStrategy":"type-guard","validationCode":"import {FSEventsWatcher} from 'jest-haste-map/watchers/FSEventsWatcher';\nif (!FSEventsWatcher.isSupported()) {\n  throw new Error('FSEventsWatcher not supported on this platform; use NodeWatcher or WatchmanWatcher.');\n}","typeGuard":"import {FSEventsWatcher} from 'jest-haste-map/watchers/FSEventsWatcher';\nfunction canUseFSEvents(): boolean {\n  return FSEventsWatcher.isSupported(); // true only if fsevents loaded (Darwin + addon present)\n}","tryCatchPattern":null,"preventionTips":["Never instantiate FSEventsWatcher without first checking isSupported().","Rely on WatcherDriver which already guards with isSupported().","Treat fsevents as optional; do not hard-fail on non-Darwin where it is expected to be absent."],"tags":["haste-map","watcher","fsevents","darwin","platform","native-module"],"analyzedSha":"f49721c78e195558b40913977c9230f5b7f559d8","analyzedAt":"2026-08-03T20:16:28.571Z","schemaVersion":2}