diff --git a/nim.cfg b/nim.cfg
index 635072488..ba9b3b9a4 100644
--- a/nim.cfg
+++ b/nim.cfg
@@ -22,6 +22,9 @@
 --excessiveStackTrace:on
 # enable metric collection
 -d:metrics
+
+# the default open files limit is too low on macOS (512), breaking the
+# "--debugger:native" build. It can be increased with `ulimit -n 1024`.
 @if not macosx:
   # add debugging symbols and original files and line numbers
   --debugger:native