syncthing/syncthing · warning · ErrWatchNotSupported

watching is not supported

Error message

watching is not supported

What it means

ErrWatchNotSupported (filesystem.go:155) is returned by Watch/StartWatcher implementations that cannot observe filesystem events — e.g. fake/in-memory filesystems used in tests, or platform/FilesystemType combinations without a change-notification backend. It signals a permanent capability gap, not a transient failure.

Source

Thrown at lib/fs/filesystem.go:155

func (evType EventType) Merge(other EventType) EventType {
	return evType | other
}

func (evType EventType) String() string {
	switch evType {
	case NonRemove:
		return "non-remove"
	case Remove:
		return "remove"
	case Mixed:
		return "mixed"
	default:
		panic("bug: Unknown event type")
	}
}

var (
	ErrWatchNotSupported  = errors.New("watching is not supported")
	ErrXattrsNotSupported = errors.New("extended attributes are not supported on this platform")
)

// Equivalents from os package.

const (
	ModePerm      = FileMode(os.ModePerm)
	ModeSetgid    = FileMode(os.ModeSetgid)
	ModeSetuid    = FileMode(os.ModeSetuid)
	ModeSticky    = FileMode(os.ModeSticky)
	ModeSymlink   = FileMode(os.ModeSymlink)
	ModeType      = FileMode(os.ModeType)
	PathSeparator = os.PathSeparator
	OptAppend     = os.O_APPEND
	OptCreate     = os.O_CREATE
	OptExclusive  = os.O_EXCL
	OptReadOnly   = os.O_RDONLY
	OptReadWrite  = os.O_RDWR

View on GitHub (pinned to 058bcd7334)

Solutions

1. Fall back to periodic scanning/rescan when watching is unsupported instead of failing
2. Feature-check the filesystem before enabling watch-dependent logic
3. For production folders on a platform without watchers, use the type that supports them or accept scanning

Example fix

// before
events, errs, err := fs.Watch(name, ignore)
if err != nil { return err }

// after
events, errs, err := fs.Watch(name, ignore)
if errors.Is(err, fs.ErrWatchNotSupported) {
    return startPeriodicRescan(fs, interval)
}
if err != nil { return err }

func canWatch(f fs.Filesystem) error {
    _, _, err := f.Watch(".", nil)
    if errors.Is(err, fs.ErrWatchNotSupported) { return err }
    return nil // probe or real support
}

events, errs, err := f.Watch(name, ignore)
if errors.Is(err, fs.ErrWatchNotSupported) {
    events, errs, err = nil, nil, startPolling(f, name, period)
}

When it happens

Trigger: Calling Watch() on a Filesystem implementation that lacks watcher support (fake fs, certain types on certain platforms); library code assuming every Filesystem can watch.

Common situations: Unit tests against fake filesystems; embedded/exotic platforms where inotify/FAM/ReadDirectoryChangesW is unavailable; generic wrapper code that calls Watch on any fs.Filesystem it receives.

Related errors

• failed to set up inotify handler. Please increase inotify li
• symlinks not supported
• failed to create {path}: {error}
• folder path not a directory
• folder path missing

AI-assisted analysis of syncthing/syncthing@058bcd7334 (2026-08-15). Data as JSON: /api/errors/dbc26cbf66d3603b. Report an issue: GitHub.