microsoft/typescript-go · error

fswatch: watcher backend unsupported on this filesystem

Error message

fswatch: watcher backend unsupported on this filesystem

What it means

Exported sentinel: the backend exists on this platform but cannot watch the target filesystem. The concrete case is fanotify on filesystems without FID support: name_to_handle_at returning EOPNOTSUPP (Docker bind mounts backed by virtiofs, gRPC FUSE, overlayfs) or fanotify_mark returning ENODEV (NTFS via fuseblk); fanotify_linux.go wraps those errnos with this sentinel. Fanotify() and Default() return a fallbackWatcher that catches it per request and retries on inotify automatically.

Source

Thrown at internal/fswatch/watcher.go:50

// 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",
	// "windows").
	Name() string
	// Available reports whether this watcher works on the current OS.
	Available() bool
	// HasFastRecursiveBackend reports whether this watcher supports efficient
	// recursive watching without requiring a full userspace tree walk. This is
	// true for Windows (ReadDirectoryChangesW subtree mode) and macOS FSEvents
	// (inherently recursive), and false for all other backends.
	HasFastRecursiveBackend() bool

View on GitHub (pinned to 1bcfa18d79)

Solutions

1. Use fswatch.Fanotify() or fswatch.Default(): both reroute unsupported directories to inotify automatically
2. If fanotify semantics are required, move the watched tree to a filesystem with FID support (ext4, xfs, btrfs)
3. When building your own fallback, key it on errors.Is(err, fswatch.ErrFilesystemUnsupported)
4. Run the watcher outside the container when the mount type cannot change

Example fix

// before
// raw primary backend with no fallback routing

// after
w := fswatch.Fanotify() // fanotify + automatic inotify fallback
watch, err := w.WatchDirectory(dir, cb)

// Prefer the auto-falling-back constructors:
w := fswatch.Fanotify()   // fanotify primary, inotify secondary
// or
w := fswatch.Default()    // already the fallback watcher on Linux

func isFilesystemUnsupported(err error) bool {
    return errors.Is(err, fswatch.ErrFilesystemUnsupported)
}

watch, err := primary.WatchDirectory(dir, cb)
if errors.Is(err, fswatch.ErrFilesystemUnsupported) {
    watch, err = fswatch.Inotify().WatchDirectory(dir, cb)
}

When it happens

Trigger: Default() or Fanotify() on Linux with kernel 5.13+ watching a directory on overlayfs or virtiofs (the default inside many Docker containers) or FUSE-backed NTFS. Any custom routing that uses the raw fanotify backend on such mounts.

Common situations: Dev tools run inside Docker containers with overlay2 storage. Docker Desktop on macOS sharing code via virtiofs or gRPC FUSE. Dual-boot machines with NTFS data disks mounted through fuseblk.

Related errors

• name_to_handle_at: %w
• fswatch: failed to watch directory %q: %w
• unable to open pipe: %w
• unable to initialize fanotify: %w
• unable to poll: %w

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