make-options-doc: builtins.toFile creates options.json without proper store path context

[Bad3r]

Description

nixos/lib/make-options-doc/default.nix uses builtins.toFile to create options.json in a way that loses store path context, triggering a warning:

warning: Using 'builtins.toFile' to create a file named 'options.json' that references the store path '/nix/store/...-source' without a proper context. The resulting file will not have a correct store reference, so this is unreliable and may stop working in the future.

Location

https://github.com/NixOS/nixpkgs/blob/master/nixos/lib/make-options-doc/default.nix#L217

options = builtins.toFile "options.json" (
  builtins.unsafeDiscardStringContext (builtins.toJSON optionsNix)
);

Context

The use of builtins.toFile with builtins.unsafeDiscardStringContext appears to be a deliberate performance optimization:

• builtins.toFile runs at evaluation time and creates the file directly in the store without a derivation (faster)
• pkgs.writeText creates a derivation that runs at build time (slower, but properly tracks dependencies)

Since builtins.toFile cannot reference store paths, unsafeDiscardStringContext is used to strip the context. This works but loses dependency tracking, which Nix now warns about.

Impact

• Currently a warning, but the message indicates this may break in future Nix versions
• Affects any NixOS configuration that builds documentation
• Triggered during nixos-rebuild, nix build, or nix eval of NixOS configurations

Suggested Fix

Replace builtins.toFile with pkgs.writeText or similar derivation-based approach that properly tracks store path context. This may have a performance impact on documentation builds.

Reproduction

Build any NixOS configuration:

nix build .#nixosConfigurations.<hostname>.config.system.build.toplevel

Metadata

• NixOS version: unstable (nixpkgs master)
• Nix version: 2.33.1

[Bad3r]

Additional context:

This warning appears to have been introduced around Nix 2.31.x (late September / early October 2025) based on user reports. The exact commit that added this warning is not documented in the release notes.

Related issues:

• home-manager #7935 - Same warning affecting home-manager documentation
• NixOS/nix #14011 - Proposal for builtin:write-file which would be a proper solution

The pattern in question:

options = builtins.toFile "options.json" (
  builtins.unsafeDiscardStringContext (builtins.toJSON optionsNix)
);

Uses unsafeDiscardStringContext to strip store path context so builtins.toFile can accept the content, but this loses dependency tracking - which Nix now warns about.

[BirdeeHub]

nixpkgs/nixos/lib/make-options-doc/default.nix

Lines 217 to 219 in 799ceb0

	options = builtins.toFile "options.json" (
	builtins.unsafeDiscardStringContext (builtins.toJSON optionsNix)
	);

Cant this just be options = builtins.toJSON (builtins.unsafeDiscardStringContext optionsNix); passAsFile = [ "options" ]; and then you can grab $optionsPath? That would solve the problem, correct? Its also practically guaranteed to be faster?

---

Also, that python script does very little. Would it not be better to just filter the invisible ones and warn on missing descriptions from within nix directly instead? Then IFD would not be a concern for the json version either. Im not 100% sure why that is in python. But if its to stay in python, we can solve this problem with passAsFile

---

Also, if it helps, the version it was added is after 2.31.3 as I can't trigger it locally on that version but I can trigger it in my github action (which is Nix (Determinate Nix 3.15.2) 2.33.1 at the moment because it works well on the mac runner)

[BirdeeHub]

Also, separate question

nixpkgs/nixos/lib/make-options-doc/default.nix

Lines 94 to 102 in 799ceb0

	documentType ? "appendix",
	# TODO deprecate "appendix" in favor of "none"
	# and/or rename function to moduleOptionDoc for clean slate
	# If you include more than one option list into a document, you need to
	# provide different ids.
	variablelistId ? "configuration-variable-list",
	# String to prefix to the option XML/HTML id attributes.
	optionIdPrefix ? "opt-",

These are not used anywhere. Why are they there?

They do get set here

nixpkgs/nixos/doc/manual/default.nix

Lines 92 to 94 in 32defc7

	documentType = "none";
	variablelistId = "test-options-list";
	optionIdPrefix = "test-opt-";

But they do literally nothing.

[BirdeeHub]

Im actually not sure I successfully solved the issue.

I improved the derivation. It was still a sound change. There was no harm in merging what I did.

Im 90% sure I solved the issue. But I might have just changed the warning from warning about builtins.toFile over to builtins.derivation. Im getting a warning for that now, but I am also doing some strange things with the docgen on my end and I think my new warning is from that and not this. Im going to need someone to double check that I succeeded or not.

However, if this does not solve it, I would assume that pkgs.writeText would not have either, as that is what pkgs.writeText does.

Regardless we NEED to strip them, as otherwise we will have to build a lot of packages to build the docs.

It is not a small performance optimization to discard the context. It is the only one that really matters. As otherwise you would build a large portion of nixpkgs to build the docs.

Edit: I found my new warning. It was indeed from my personal modifications and not from using passAsFile on these. I am more sure that I successfully solved the issue now. __structuredAttrs also works, which I used in my docgen for my wrapper modules project

[MattSturgeon]

Edit: I found my new warning. It was indeed from my modifications. I am more sure that I successfully solved the issue now.

Good to hear! Thanks for verifying. I'll close this then.

Do we need to backport this? I assume some people might end up evaluating 25.11 with a new enough nix to get the warnings.
EDIT: #486456

[BirdeeHub]

Sure why not backport it. It is just a warning, but since people use warnings-as-errors and stuff, it is probably worth it. And the change is something that has worked for many years anyway.

[BirdeeHub]

Ok so, bad news. I don't think I fixed it anymore I think I was getting some weird cache action when I tested it that made me think it was fixed.

Good news. I also did not break it and likely made it faster.

It warns about using builtins.derivation for the same purpose now.

FWIW I have this which doesn't warn but for a different project.

But I also think most of what I am doing in that particular section I linked is possibly overcomplicated and only necessary because I was already using __structuredAttrs

I think this because the following also doesn't warn or anything when you build it

pkgs.stdenv.mkDerivation {
  passAsFile = [ "test" ];
  test = builtins.unsafeDiscardStringContext "${pkgs.hello} --greeting ${pkgs.coreutils}";
  buildPhase = "cat \"$testPath\" > $out";
  name = "testdrv";
  src = "";
  dontUnpack = true;
}

Likewise neither does this

pkgs.runCommand "test" {
  passAsFile = [ "test" ];
  test = builtins.unsafeDiscardStringContext "${pkgs.hello} --greeting ${pkgs.coreutils}";
}
"cat \"$testPath\" > $out"

And from testing, doing the above also does not provision it to your system.

So at the very least, what I did was sound but maybe not sufficient.

[BirdeeHub]

For the next person to test this easier than the way I was trying to test it originally, a flake

{
  inputs.nixpkgs.url = "git+file:/home/<YOUR_USERNAME>/YOUR/LOCAL/nixpkgs";
  outputs =
    { nixpkgs, ... }:
    {
      packages = nixpkgs.lib.genAttrs nixpkgs.lib.platforms.all (
        system:
        let
          pkgs = import nixpkgs { inherit system; };
        in
        {
          default =
            (pkgs.nixosOptionsDoc {
              options =
                (nixpkgs.lib.nixosSystem {
                  inherit (pkgs) system;
                  modules = [ ];
                }).options;
            }).optionsJSON;
        }
      );
    };
}

I have no idea how to improve it from here, nothing I am trying is working, although this is a very reliable way to test it it seems.

I am using determinate nix to trigger this issue. I changed my nix version so that I could reproduce the bug, and that was what I did in order to do that. I forgot that this might be specific to that version.