diff --git a/lib/filesystem.nix b/lib/filesystem.nix
index e6ebbeb6b1f5f..b7fd424cf4899 100644
--- a/lib/filesystem.nix
+++ b/lib/filesystem.nix
@@ -311,7 +311,7 @@ in
       newScope? :: AttrSet -> scope,
       directory :: Path,
       recurseIntoDirectory? :: (args -> AttrSet) -> args -> AttrSet,
-      ...
+      recurseArgs? :: Any
     }) -> AttrSet
     ```
 
@@ -349,6 +349,9 @@ in
       ```
       :::
 
+    `recurseArgs`
+    : Optional argument, which can be used to hold data used by `recurseIntoDirectory`
+
     # Examples
     :::{.example}
     ## Basic use of `lib.packagesFromDirectoryRecursive`
@@ -421,8 +424,11 @@ in
     in
     {
       callPackage,
+      newScope ? throw "lib.packagesFromDirectoryRecursive: newScope wasn't passed in args",
       directory,
-      # recurseIntoDirectory can modify the function used when processing directory entries; see nixdoc above
+      # recurseIntoDirectory can modify the function used when processing directory entries
+      #  and recurseArgs can (optionally) hold data for its use ; see nixdoc above
+      recurseArgs ? throw "lib.packagesFromDirectoryRecursive: recurseArgs wasn't passed in args",
       recurseIntoDirectory ?
         if args ? newScope then
           # `processDir` is the same function as defined above
@@ -442,7 +448,6 @@ in
         else
           # otherwise, no modification is necessary
           id,
-      ...
     }@args:
     let
       defaultPath = append directory "package.nix";
diff --git a/nixos/doc/manual/release-notes/rl-2505.section.md b/nixos/doc/manual/release-notes/rl-2505.section.md
index be10531c3e4cf..ee91591397c49 100644
--- a/nixos/doc/manual/release-notes/rl-2505.section.md
+++ b/nixos/doc/manual/release-notes/rl-2505.section.md
@@ -146,6 +146,9 @@
 - `renovate` was updated to v39. See the [upstream release notes](https://docs.renovatebot.com/release-notes-for-major-versions/#version-39) for breaking changes.
   Like upstream's docker images, renovate now runs on NodeJS 22.
 
+- [`lib.packagesFromDirectoryRecursive`] now rejects unknown arguments.
+  [`lib.packagesFromDirectoryRecursive`]: https://nixos.org/manual/nixpkgs/stable/#function-library-lib.filesystem.packagesFromDirectoryRecursive
+
 - The behavior of the `networking.nat.externalIP` and `networking.nat.externalIPv6` options has been changed. `networking.nat.forwardPorts` now only forwards packets destined for the specified IP addresses.
 
 - `python3Packages.jaeger-client` was removed because it was deprecated upstream. [OpenTelemetry](https://opentelemetry.io) is the recommended replacement.
@@ -271,7 +274,7 @@
   - Overriding Wayland compositor is possible using `enableWaylandSession` option, but you might need to take care [`xfce4-session`](https://gitlab.xfce.org/xfce/xfce4-session/-/merge_requests/49), [`dbus-update-activation-environment`](https://github.com/labwc/labwc/blob/eaf11face68ee1f1bcc7ce1498304ca8c108c8ba/src/config/session.c#L234) and [`systemctl --user import-environment`](https://github.com/labwc/labwc/blob/eaf11face68ee1f1bcc7ce1498304ca8c108c8ba/src/config/session.c#L239) on startup.
   - For new Xfce installations, default panel layout has [changed](https://gitlab.xfce.org/xfce/xfce4-panel/-/merge_requests/158/diffs) to not include external panel plugins by default. You can still add them yourself using the "Panel Preferences" dialog.
 
-- `lib.packagesFromDirectoryRecursive` can now construct nested scopes matching the directory tree passed as input.
+- [`lib.packagesFromDirectoryRecursive`] can now construct nested scopes matching the directory tree passed as input.
 
 - GOverlay has been updated to 1.2, please check the [upstream changelog](https://github.com/benjamimgois/goverlay/releases) for more details.