What causes "fswatch: path must be absolute" in microsoft/typescript-go?

Absolutize with filepath.Abs(dir) before subscribing

fswatch: path must be absolute

Error message

fswatch: path must be absolute

What it means

Sentinel error returned by WatchDirectory and WatchFile when the cleaned path is not absolute. The API requires absolute paths because event delivery and internal bookkeeping key on them; filepath.Clean is applied first but never absolutizes, so relative inputs like "src" or "./out" are rejected. On Windows, IsAbs requires a drive-rooted (C:\x) or UNC (\\server\share\x) form, so volume-relative paths like "C:foo" also fail.

Source

Thrown at internal/fswatch/watcher.go:25

	"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
// available on the current platform.
var ErrUnavailable = errors.New("fswatch: watcher not available on this platform")

// ErrFilesystemUnsupported indicates that the active watcher backend cannot

View on GitHub (pinned to 1bcfa18d79)

Solutions

Absolutize with filepath.Abs(dir) before subscribing
Derive watch paths from a rooted base directory constant
On Windows, normalize to drive-rooted or UNC form before the call

Example fix

// before
watch, err := fswatch.Default().WatchDirectory("out", cb)

// after
dir, err := filepath.Abs("out")
if err != nil {
    return err
}
watch, err := fswatch.Default().WatchDirectory(dir, cb)

Defensive patterns

Strategy: validation

Validate before calling

if !filepath.IsAbs(dir) {
    abs, err := filepath.Abs(dir)
    if err != nil {
        return err
    }
    dir = abs
}

Try / catch

if _, err := w.WatchDirectory(dir, cb); err != nil {
    if err.Error() == "fswatch: path must be absolute" {
        dir, _ = filepath.Abs(dir)
        // retry with the absolutized path
    }
}

Prevention

Absolutize every watch path once at configuration load
Derive watch paths from rooted constants, not raw user input
Expand ~ and environment variables before passing paths
On Windows, normalize to drive-rooted or UNC form

When it happens

Trigger: Passing a working-directory-relative path such as "out" or "../src". Passing a volume-relative path such as "C:tmp" on Windows. Building watch paths by joining user input onto an empty base.

Common situations: CLI tools forwarding user arguments straight to the watcher. Cross-platform code assuming Unix separators. Tests using relative fixture paths. Config files with '~' that was never expanded.

Related errors

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