microsoft/typescript-go · error

fswatch: callback must not be nil

Error message

fswatch: callback must not be nil

What it means

Sentinel error returned when a nil WatchCallback is passed. WatchDirectories checks each request's Callback and rolls back every watch prepared so far before returning it; WatchDirectory delegates to the same path, and WatchFile checks it directly. It signals a programming error at the call site, not an environmental condition.

Source

Thrown at internal/fswatch/watcher.go:17

package fswatch

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

View on GitHub (pinned to 1bcfa18d79)

Solutions

1. Pass a non-nil callback function
2. Fail fast in your own wrapper: reject nil callbacks before calling fswatch
3. If you truly need a no-op, pass an empty function literal instead of nil

Example fix

// before
watch, err := w.WatchDirectory(dir, nil)

// after
noop := func(events []fswatch.Event, err error) {}
watch, err := w.WatchDirectory(dir, noop)

if cb == nil {
    return errors.New("callback must not be nil")
}

When it happens

Trigger: Calling WatchDirectory(dir, nil). Passing a nil func variable. Constructing WatchDirectoryRequest with a zero-value Callback field.

Common situations: Optional-callback layers where nil slips through. Struct literals like WatchDirectoryRequest{Dir: d} with the Callback field forgotten. Refactors that rename the callback parameter and leave the argument position empty.

Related errors

• fswatch: cannot watch a root path
• fswatch: path must be absolute
• Expected ${pkgName} to declare exactly one bin entry named $
• Cannot run a temporary file update on an inactive snapshot
• Snapshot is disposed

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