diff --git a/doc/release-notes/rl-2505.section.md b/doc/release-notes/rl-2505.section.md
index 4eeb8f1c76d3..2f009a44bd8d 100644
--- a/doc/release-notes/rl-2505.section.md
+++ b/doc/release-notes/rl-2505.section.md
@@ -69,6 +69,9 @@
 
 - The `virtualisation.hypervGuest.videoMode` option has been removed. Standard tooling can now be used to configure display modes for Hyper-V VMs.
 
+- [`lib.packagesFromDirectoryRecursive`] now rejects unknown arguments.
+  [`lib.packagesFromDirectoryRecursive`]: https://nixos.org/manual/nixpkgs/stable/#function-library-lib.filesystem.packagesFromDirectoryRecursive
+
 ### Deprecations {#sec-nixpkgs-release-25.05-lib-deprecations}
 
 - `functor` is an implementation detail and should not be relied upon, but since its status wasn't clear and it has had some use cases without alternatives, changes are being handled as gracefully as possible. Deprecations within functor:
@@ -85,6 +88,6 @@
 
 - `rustPlatform.buildRustPackage` stops handling the deprecated argument `cargoSha256`. Out-of-tree packages that haven't migrated from `cargoSha256` to `cargoHash` now receive errors.
 
-### Other notable changes {#sec-release-25.05-lib-notable-changes}
+### Additions and Improvements {#sec-nixpkgs-release-25.05-lib-additions-improvements}
 
-- `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.
diff --git a/lib/filesystem.nix b/lib/filesystem.nix
index a3abab391d2a..4218c3fa4749 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 hold data used by `recurseIntoDirectory`
+
     # Examples
     :::{.example}
     ## Basic use of `lib.packagesFromDirectoryRecursive`
@@ -438,28 +441,12 @@ 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 ?
-        if args ? newScope then
-          # `processDir` is the same function as defined above
-          # `args` are the arguments passed to (this recursive call of) `packagesFromDirectoryRecursive`
-          processDir: { newScope, ... }@args:
-            # Create a new scope and mark it `recurseForDerivations`.
-            # This lets the packages refer to each other.
-            # See:
-            #  [lib.makeScope](https://nixos.org/manual/nixpkgs/unstable/#function-library-lib.customisation.makeScope) and
-            #  [lib.recurseIntoAttrs](https://nixos.org/manual/nixpkgs/unstable/#function-library-lib.customisation.makeScope)
-            recurseIntoAttrs (makeScope newScope (self:
-              # generate the attrset representing the directory, using the new scope's `callPackage` and `newScope`
-              processDir (args // {
-                inherit (self) callPackage newScope;
-              })
-            ))
-        else
-          # otherwise, no modification is necessary
-          id,
-      ...
+      # recurseIntoDirectory can modify the function used when processing directory entries
+      #  and recurseArgs can (optionally) hold data for its use ; see function documentation
+      recurseArgs ? throw "lib.packagesFromDirectoryRecursive: recurseArgs wasn't passed in args",
+      recurseIntoDirectory ? defaultRecurse,
     }@args:
     let
       defaultPath = append directory "package.nix";