diff --git a/pkgs/watcher/CHANGELOG.md b/pkgs/watcher/CHANGELOG.md
index 91d5d4f81..06d8bdfba 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 8caf09f8a..9cc27eeed 100644
--- a/pkgs/watcher/lib/src/directory_watcher.dart
+++ b/pkgs/watcher/lib/src/directory_watcher.dart
@@ -20,6 +20,11 @@ import 'directory_watcher/windows.dart';
 /// 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 143aa3172..a70210364 100644
--- a/pkgs/watcher/lib/src/file_watcher.dart
+++ b/pkgs/watcher/lib/src/file_watcher.dart
@@ -16,6 +16,11 @@ import 'file_watcher/native.dart';
 ///
 /// 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].
   ///