microsoft/typescript-go · error

fswatch: watcher not available on this platform

Error message

fswatch: watcher not available on this platform

What it means

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.

Source

Thrown at internal/fswatch/watcher.go:41

// errNotAbsolute is returned by [Watcher.WatchDirectory] and
// [Watcher.WatchFile] when the supplied path is not absolute.
var errNotAbsolute = errors.New("fswatch: path must be absolute")

// ErrOverflow indicates that the kernel event queue overflowed and
// some filesystem changes were missed. The watch remains
// active; further events will continue to be delivered. Callers
// should treat this as a signal to rescan the watched directory.
var ErrOverflow = errors.New("fswatch: event overflow; some changes were missed")

// ErrWatchTerminated indicates that the watch was terminated due to
// an unrecoverable error (e.g. the watched directory was deleted or
// the watch descriptor was revoked). No further events will be
// delivered. Call Close to release remaining state.
var ErrWatchTerminated = errors.New("fswatch: watch terminated")

// ErrUnavailable indicates that a requested watcher is not
// available on the current platform.
var ErrUnavailable = errors.New("fswatch: watcher not available on this platform")

// ErrFilesystemUnsupported indicates that the active watcher backend cannot
// operate on the target filesystem, even though the backend is available on
// the current platform. This happens, for example, with the fanotify backend
// on filesystems that do not support FID-based watching: name_to_handle_at
// returning EOPNOTSUPP (some Docker bind mounts backed by virtiofs, gRPC FUSE,
// or overlayfs) or fanotify_mark returning ENODEV (e.g. NTFS mounted via
// fuseblk).
var ErrFilesystemUnsupported = errors.New("fswatch: watcher backend unsupported on this filesystem")

// Watcher represents a filesystem watching implementation.
// Use one of the constructor functions ([Inotify], [FSEvents], [Kqueue],
// [Windows]) to obtain a value, or [Default] for the platform default.
//
// All watchers exist on every platform. Subscribing with a watcher that
// is not supported on the current OS returns [ErrUnavailable].
type Watcher interface {
	// Name returns a stable identifier ("inotify", "fsevents", "kqueue",

View on GitHub (pinned to 1bcfa18d79)

Solutions

1. Use fswatch.Default() instead of a named constructor; it picks the right backend for GOOS
2. Guard explicit backends with watcher.Available() before subscribing
3. Branch on errors.Is(err, fswatch.ErrUnavailable) and fall back to Default()
4. On OSes with no backend, supply your own polling implementation

Example fix

// before
watch, err := fswatch.Inotify().WatchDirectory(dir, cb) // fails on macOS/Windows

// after
w := fswatch.Inotify()
if !w.Available() {
    w = fswatch.Default()
}
watch, err := w.WatchDirectory(dir, cb)

if !w.Available() {
    w = fswatch.Default()
}

func isUnavailable(err error) bool {
    return errors.Is(err, fswatch.ErrUnavailable)
}

watch, err := w.WatchDirectory(dir, cb)
if errors.Is(err, fswatch.ErrUnavailable) {
    watch, err = fswatch.Default().WatchDirectory(dir, cb)
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• fswatch: path must be absolute
• Could not find a TypeScript executable in the extension pack
• Unable to resolve ${platformPackageName}. Either your platfo
• fswatch: callback must not be nil
• fswatch: cannot watch a root path

AI-assisted analysis of microsoft/typescript-go@1bcfa18d79 (2026-08-16). Data as JSON: /api/errors/11e36fc262e2ee15. Report an issue: GitHub.