microsoft/typescript-go · error

fswatch: cannot watch a root path

Error message

fswatch: cannot watch a root path

What it means

Sentinel error returned by WatchFile when the path is a filesystem root such as / on Unix or C:\ on Windows. WatchFile is implemented by watching the parent directory, and a root has no parent (filepath.Dir(path) == path), so the request is rejected before any OS watch is created. The sentinel is unexported, so callers detect it by message or prevent it with validation.

Source

Thrown at internal/fswatch/watcher.go:21

import (
	"errors"
	"fmt"
	"os"
	"path/filepath"
	"runtime"
	"slices"
	"strings"
	"sync"
	"syscall"

	"github.com/microsoft/typescript-go/internal/nativepath"
)

var errNilCallback = errors.New("fswatch: callback must not be nil")

// errRootPath is returned by WatchFile when the supplied path is a
// filesystem root with no parent directory to watch.
var errRootPath = errors.New("fswatch: cannot watch a root path")

// 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

View on GitHub (pinned to 1bcfa18d79)

Solutions

1. Watch a concrete file, or use WatchDirectory if you want events for the root itself
2. Reject root paths in your own input validation before calling WatchFile
3. Sanitize user-supplied paths (filepath.Clean, filepath.Abs) and reject Dir(path) == path

Example fix

// before
watch, err := w.WatchFile(rootPath, cb) // rootPath == "/"

// after
if filepath.Dir(p) == p {
    return errors.New("cannot watch a filesystem root")
}
watch, err := w.WatchFile(p, cb)

p := filepath.Clean(path)
if !filepath.IsAbs(p) {
    return errors.New("path must be absolute")
}
if filepath.Dir(p) == p {
    return errors.New("cannot watch a filesystem root")
}

if _, err := w.WatchFile(p, cb); err != nil {
    if err.Error() == "fswatch: cannot watch a root path" {
        // rejected input: use WatchDirectory on the root instead
    }
}

When it happens

Trigger: WatchFile("/") on Unix. WatchFile("C:\") on Windows. Any cleaned absolute path whose Dir equals itself.

Common situations: Configuration that accepts a file path but is fed a mount point. Path joins that collapse to the root (for example filepath.Join("/", "..")). Watch targets derived from user input without normalization checks.

Related errors

• fswatch: path must be absolute
• Cannot create directory: a file already exists at "/${segmen
• Invalid file path: "${path}"
• fswatch: callback must not be nil
• Expected ${pkgName} to declare exactly one bin entry named $

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