{"record":{"id":"11e36fc262e2ee15","repo":"microsoft/typescript-go","slug":"fswatch-watcher-not-available-on-this-platform","errorCode":null,"errorMessage":"fswatch: watcher not available on this platform","messagePattern":"fswatch: watcher not available on this platform","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/fswatch/watcher.go","lineNumber":41,"sourceCode":"// errNotAbsolute is returned by [Watcher.WatchDirectory] and\n// [Watcher.WatchFile] when the supplied path is not absolute.\nvar errNotAbsolute = errors.New(\"fswatch: path must be absolute\")\n\n// ErrOverflow indicates that the kernel event queue overflowed and\n// some filesystem changes were missed. The watch remains\n// active; further events will continue to be delivered. Callers\n// should treat this as a signal to rescan the watched directory.\nvar ErrOverflow = errors.New(\"fswatch: event overflow; some changes were missed\")\n\n// ErrWatchTerminated indicates that the watch was terminated due to\n// an unrecoverable error (e.g. the watched directory was deleted or\n// the watch descriptor was revoked). No further events will be\n// delivered. Call Close to release remaining state.\nvar ErrWatchTerminated = errors.New(\"fswatch: watch terminated\")\n\n// ErrUnavailable indicates that a requested watcher is not\n// available on the current platform.\nvar ErrUnavailable = errors.New(\"fswatch: watcher not available on this platform\")\n\n// ErrFilesystemUnsupported indicates that the active watcher backend cannot\n// operate on the target filesystem, even though the backend is available on\n// the current platform. This happens, for example, with the fanotify backend\n// on filesystems that do not support FID-based watching: name_to_handle_at\n// returning EOPNOTSUPP (some Docker bind mounts backed by virtiofs, gRPC FUSE,\n// or overlayfs) or fanotify_mark returning ENODEV (e.g. NTFS mounted via\n// fuseblk).\nvar ErrFilesystemUnsupported = errors.New(\"fswatch: watcher backend unsupported on this filesystem\")\n\n// Watcher represents a filesystem watching implementation.\n// Use one of the constructor functions ([Inotify], [FSEvents], [Kqueue],\n// [Windows]) to obtain a value, or [Default] for the platform default.\n//\n// All watchers exist on every platform. Subscribing with a watcher that\n// is not supported on the current OS returns [ErrUnavailable].\ntype Watcher interface {\n\t// Name returns a stable identifier (\"inotify\", \"fsevents\", \"kqueue\",","sourceCodeStart":23,"sourceCodeEnd":59,"githubUrl":"https://github.com/microsoft/typescript-go/blob/1bcfa18d79a3be41772223d5c05dfe4480e614ff/internal/fswatch/watcher.go#L23-L59","documentation":"Exported sentinel returned when the requested watcher backend does not run on the current OS. All backends compile everywhere, but each platform watcher's factory is nil off-platform; WatchDirectories returns the error before doing any work, and getImpl returns it if the factory is missing. Default() selects the correct backend per GOOS, and Available() reports support before you subscribe.","triggerScenarios":"Inotify() or Fanotify() on macOS or Windows. FSEvents() on Linux or Windows. Kqueue() on Linux or Windows. Any watcher on an OS outside the supported set, where Default() itself returns an 'unsupported' watcher.","commonSituations":"Cross-platform code hardcoding a backend per feature flag. Tests written on one OS exercising another platform's watcher. Feature detection that forgets the Available() check. Solaris/illumos or Plan 9 builds where no backend exists.","solutions":["Use fswatch.Default() instead of a named constructor; it picks the right backend for GOOS","Guard explicit backends with watcher.Available() before subscribing","Branch on errors.Is(err, fswatch.ErrUnavailable) and fall back to Default()","On OSes with no backend, supply your own polling implementation"],"exampleFix":"// before\nwatch, err := fswatch.Inotify().WatchDirectory(dir, cb) // fails on macOS/Windows\n\n// after\nw := fswatch.Inotify()\nif !w.Available() {\n    w = fswatch.Default()\n}\nwatch, err := w.WatchDirectory(dir, cb)","handlingStrategy":"validation","validationCode":"if !w.Available() {\n    w = fswatch.Default()\n}","typeGuard":"func isUnavailable(err error) bool {\n    return errors.Is(err, fswatch.ErrUnavailable)\n}","tryCatchPattern":"watch, err := w.WatchDirectory(dir, cb)\nif errors.Is(err, fswatch.ErrUnavailable) {\n    watch, err = fswatch.Default().WatchDirectory(dir, cb)\n}","preventionTips":["Default to fswatch.Default() unless you need a specific backend","Check Available() before using a named constructor","Never assume a backend exists because the code compiles: all watchers exist on every platform","Gate platform-specific tests on Available()"],"tags":["platform","availability","api-misuse","cross-platform"],"backgroundTag":null,"analyzedSha":"1bcfa18d79a3be41772223d5c05dfe4480e614ff","analyzedAt":"2026-08-16T02:12:00.115Z","schemaVersion":2},"datasetVersion":"2026-08-16T03:17:38.424Z"}