microsoft/typescript-go · warning

fswatch: event overflow; some changes were missed

Error message

fswatch: event overflow; some changes were missed

What it means

Exported sentinel delivered on the WatchCallback when the kernel event queue overflowed and some changes were missed. The watch remains active and later events still arrive; this is a signal to rescan, not a failure to recover from. On Windows it maps to ERROR_NOTIFY_ENUM_DIR (processCompletion sets it via events.setError); on Linux it corresponds to inotify/fanotify queue overflow.

Source

Thrown at internal/fswatch/watcher.go:31

	"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
// 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).

View on GitHub (pinned to 1bcfa18d79)

Solutions

1. On ErrOverflow, rescan the watched directory and rebuild derived state; do not attempt to replay missed events
2. Keep callback bodies minimal; enqueue work and process it elsewhere so the queue drains fast
3. For known bulk operations, skip watching during the operation and do one full rescan afterwards

Example fix

// before
func(events []fswatch.Event, err error) {
    if err != nil {
        log.Fatal(err) // wrong: overflow is recoverable
    }
    apply(events)
}

// after
func(events []fswatch.Event, err error) {
    if errors.Is(err, fswatch.ErrOverflow) {
        rescan(dir) // rebuild state; watch is still live
        return
    }
    if err != nil {
        return // terminal errors handled elsewhere
    }
    apply(events)
}

func isOverflow(err error) bool {
    return errors.Is(err, fswatch.ErrOverflow)
}

cb := func(events []fswatch.Event, err error) {
    if errors.Is(err, fswatch.ErrOverflow) {
        rescanAndRebuild(dir) // watch stays active; missed changes need a rescan
        return
    }
    if err != nil {
        return // terminal: handled elsewhere
    }
    apply(events)
}

When it happens

Trigger: Bulk changes fast enough to exceed the kernel buffer between drains: git checkout, npm install, tar extraction. Callback work slow enough that events accumulate behind it. Windows network shares running the shrunken 64 KB buffer after an ERROR_INVALID_PARAMETER recovery.

Common situations: Package managers and build tools touching thousands of files at once. Watching node_modules or build output recursively. Consumers doing heavy processing inside the callback instead of deferring it.

Related errors

• fswatch: path must be absolute
• fswatch: watch terminated
• fswatch: watcher not available on this platform
• %w: %w

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