Document Linux watcher exhaustion error. (#2243)
diff --git a/pkgs/watcher/CHANGELOG.md b/pkgs/watcher/CHANGELOG.md
index 91d5d4f..06d8bdf 100644
--- a/pkgs/watcher/CHANGELOG.md
+++ b/pkgs/watcher/CHANGELOG.md
@@ -26,6 +26,7 @@
as files, matching the behavior of the Linux and MacOS watchers.
- Bug fix: with `PollingDirectoryWatcher`, fix spurious modify event emitted
because of a file delete during polling.
+- Document behavior on Linux if the system watcher limit is hit.
## 1.1.4
diff --git a/pkgs/watcher/lib/src/directory_watcher.dart b/pkgs/watcher/lib/src/directory_watcher.dart
index 8caf09f..9cc27ee 100644
--- a/pkgs/watcher/lib/src/directory_watcher.dart
+++ b/pkgs/watcher/lib/src/directory_watcher.dart
@@ -20,6 +20,11 @@
/// the message "Directory watcher closed unexpectedly" on the event stream. The
/// code using the watcher needs to do additional work to account for the
/// dropped events, for example by recomputing interesting files from scratch.
+///
+/// On Linux, the underlying SDK `Directory.watch` fails if the system limit on
+/// watchers has been reached. If this happens the SDK exception is thrown, it
+/// is a `FileSystemException` with message `Failed to watch path` and
+/// OSError `No space left on device`, `errorCode = 28`.
abstract class DirectoryWatcher implements Watcher {
/// The directory whose contents are being monitored.
@Deprecated('Expires in 1.0.0. Use DirectoryWatcher.path instead.')
diff --git a/pkgs/watcher/lib/src/file_watcher.dart b/pkgs/watcher/lib/src/file_watcher.dart
index 143aa31..a702103 100644
--- a/pkgs/watcher/lib/src/file_watcher.dart
+++ b/pkgs/watcher/lib/src/file_watcher.dart
@@ -16,6 +16,11 @@
///
/// If the file is deleted and quickly replaced (when a new file is moved in its
/// place, for example) this will emit a [ChangeType.MODIFY] event.
+///
+/// On Linux, the underlying SDK `File.watch` fails if the system limit on
+/// watchers has been reached. If this happens the SDK exception is thrown, it
+/// is a `FileSystemException` with message `Failed to watch path` and
+/// OSError `No space left on device`, `errorCode = 28`.
abstract class FileWatcher implements Watcher {
/// Creates a new [FileWatcher] monitoring [file].
///
