{"record":{"id":"0c0fc7cbfcb62a8d","repo":"microsoft/typescript-go","slug":"fswatch-cannot-watch-a-root-path","errorCode":null,"errorMessage":"fswatch: cannot watch a root path","messagePattern":"fswatch: cannot watch a root path","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/fswatch/watcher.go","lineNumber":21,"sourceCode":"import (\n\t\"errors\"\n\t\"fmt\"\n\t\"os\"\n\t\"path/filepath\"\n\t\"runtime\"\n\t\"slices\"\n\t\"strings\"\n\t\"sync\"\n\t\"syscall\"\n\n\t\"github.com/microsoft/typescript-go/internal/nativepath\"\n)\n\nvar errNilCallback = errors.New(\"fswatch: callback must not be nil\")\n\n// errRootPath is returned by WatchFile when the supplied path is a\n// filesystem root with no parent directory to watch.\nvar errRootPath = errors.New(\"fswatch: cannot watch a root path\")\n\n// 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","sourceCodeStart":3,"sourceCodeEnd":39,"githubUrl":"https://github.com/microsoft/typescript-go/blob/1bcfa18d79a3be41772223d5c05dfe4480e614ff/internal/fswatch/watcher.go#L3-L39","documentation":"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.","triggerScenarios":"WatchFile(\"/\") on Unix. WatchFile(\"C:\\\") on Windows. Any cleaned absolute path whose Dir equals itself.","commonSituations":"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.","solutions":["Watch a concrete file, or use WatchDirectory if you want events for the root itself","Reject root paths in your own input validation before calling WatchFile","Sanitize user-supplied paths (filepath.Clean, filepath.Abs) and reject Dir(path) == path"],"exampleFix":"// before\nwatch, err := w.WatchFile(rootPath, cb) // rootPath == \"/\"\n\n// after\nif filepath.Dir(p) == p {\n    return errors.New(\"cannot watch a filesystem root\")\n}\nwatch, err := w.WatchFile(p, cb)","handlingStrategy":"validation","validationCode":"p := filepath.Clean(path)\nif !filepath.IsAbs(p) {\n    return errors.New(\"path must be absolute\")\n}\nif filepath.Dir(p) == p {\n    return errors.New(\"cannot watch a filesystem root\")\n}","typeGuard":null,"tryCatchPattern":"if _, err := w.WatchFile(p, cb); err != nil {\n    if err.Error() == \"fswatch: cannot watch a root path\" {\n        // rejected input: use WatchDirectory on the root instead\n    }\n}","preventionTips":["Reject root paths in input validation before calling WatchFile","Sanitize user-supplied paths with Clean and Abs before use","Use WatchDirectory for mount points and drive roots"],"tags":["api-misuse","validation","paths"],"backgroundTag":null,"analyzedSha":"1bcfa18d79a3be41772223d5c05dfe4480e614ff","analyzedAt":"2026-08-16T02:12:00.115Z","schemaVersion":2},"datasetVersion":"2026-08-16T03:17:38.424Z"}