When a Mac file watcher misses edits, first determine whether the change reaches the watched folder, whether the application sees filesystem events, and whether it filters or fails to process them. Reproduce one missed change in a small, known file, then compare that result with a file in the large project. This sequence helps separate project configuration from event delivery and application processing.

1. Confirm the exact path and change

In the affected app, check which folder is open as the workspace and confirm the edited file is inside that folder. A file can appear in an editor while being outside the watched root; symbolic links may also behave differently from ordinary nested folders. For example, VS Code documents that its macOS watcher uses FSEvents, that symbolic links are not followed automatically, and that its watcher exclusion setting can omit paths. Those details apply to VS Code, not every Mac app, so check the equivalent workspace and exclusion settings in your own tool. VS Code: File Watcher Issues

Save a simple edit to a file directly inside the project, then check whether the application reacts. If only a generated, ignored, linked, or deeply nested path fails, investigate that path’s inclusion and workspace-root relationship before treating it as a macOS-wide problem. If the project is on a mapped network drive or uses a third-party filesystem, test a copy on the Mac’s local disk. VS Code warns those filesystems are not guaranteed to produce events; that is a reason to compare environments, not proof that every such volume fails.

2. Check whether the application received events

File-system notifications are not a promise of one precise callback for every individual edit. Apple’s FSEvents documentation says events can be coalesced; when the MustScanSubDirs flag is set, a client must recursively rescan the indicated directory. Dropped-event flags indicate buffering problems and require a full scan of watched directories. This means a well-behaved watcher needs to reconcile the directory’s current contents, rather than relying only on a perfect sequence of notifications. Apple: Using the File System Events API, Apple: FSEventStreamEventFlags

Look for watcher logs or diagnostics in the application that is missing the change. For VS Code, its documentation describes enabling verbose file-watcher logging and inspecting the relevant log output. Other apps may expose different diagnostics or none at all. If the log reports dropped events, exclusions, a stale root, or a watcher error, preserve that message and follow the app’s own recovery steps; restarting the watcher or app can be a useful controlled comparison, but does not identify the underlying cause by itself.

3. Use fs_usage to inspect filesystem activity

macOS includes fs_usage, which displays ongoing filesystem-related system-call activity. It can help establish whether the relevant application is touching files during a reproduction, but it is not an FSEvents event viewer and cannot prove that the watcher received or processed a notification. Apple notes that access controls apply and that root access may be required. Apple: Examining File-System Usage

In Terminal, reproduce the issue while observing the named application. Substitute its actual process name for YourApp (for example, an app’s process name may differ from its display name):

sudo fs_usage -w YourApp

Stop the live display with Control-C after the brief reproduction. The output can be busy, so focus on the time of the edit and relevant paths. If the process name is uncertain, consult the application’s documentation or Activity Monitor; do not assume filtering by a guessed name will show the right process. fs_usage is a diagnostic aid for file activity, not a command to reset or repair a watcher.

4. Compare scale and access conditions

Repeat the same edit in a small local test folder that the app can watch. If that works while the large project fails, compare project-specific exclusions, symlinks, generated directories, and any remote or provider-backed paths. Large trees create more work for both event handling and rescanning; Apple’s guidance makes clear that notifications may require recursive scans, while the application decides how to handle that work. The size correlation alone does not establish an operating-system event-queue limit.

Check whether the affected app can access the project location. macOS privacy controls and App Sandbox rules can restrict access to folders, and Apple documents that access to protected locations may require user authorization in System Settings. Review the app’s permission state under System Settings > Privacy & Security, and grant only the access needed for the task. A permission issue may prevent useful file access even when the path appears in the app. Apple: Accessing Files from the macOS App Sandbox

5. Choose the next step from the evidence

If the small local folder works, send the app developer a minimal reproduction with the project location type, affected path pattern, relevant watcher log, and whether a symlink or exclusion is involved. If both small and large local folders fail, update the app and check its macOS-version-specific issue tracker or support guidance; report the macOS version and app version. Avoid deleting project data or changing system security settings as a speculative fix. The useful diagnosis is the narrowest reproducible condition: one app, one path, one edit, and one observable failure.

Sources