NixOS upgrade or `nixos-rebuild build` or `switch` fails with `manual-combined.drv' failed with exit code 3`

Was trying to upgrade from 20.03 to 20.09 (following the NixOS manual’s upgrade instructions and these steps for NixOS) but got an error during nixos-rebuild switch --upgrade similar to this:

manual-combined.xml:74245: element link: validity error : IDREF attribute linkend references an unknown ID "opt-services.awstats"
 74241       instead of dynamic cgi pages over <link linkend="opt-services.httpd">apache</link>.
 74242      </para>
 74243      <para>
 74244       Minor changes will be required to migrate existing configurations. Details of the
 74245       required changes can seen by looking through the <link linkend="opt-services.awstats">awstats</link>
 74246       module.
 74247      </para>

manual-combined.xml fails to validate
builder for '/nix/store/i8hp93d1140swks3723154vmhynn8ks0-nixos-manual-combined.drv' failed with exit code 3

(pulled from nixpkgs issue #76493 as I forgot to save mine).

Root causes with fixes

Issues with the NixOS manual

If the error is followed by lines referring to the NixOS manual, such as in nixpkgs issue #76493 below, then you may be trying to build from an unstable channel or it’s a bug that should be reported. (See aforementioned ticket, it’s short.)

cannot build derivation '/nix/store/y338xjajngcw622cbhrzahq2yvj9ld06-nixos-manpages.drv': 1 dependencies couldn't be built
cannot build derivation '/nix/store/g20gk7v7dq6bqki6g3w0kr233kdhjirb-nixos-manual-html.drv': 1 dependencies couldn't be built
cannot build derivation '/nix/store/lwcdyz99jl6gkicxblmxr1s8x9rxckfs-nixos-help.drv': 1 dependencies couldn't be built
cannot build derivation '/nix/store/a6p161x1kyq9vwwmcm62b1yn68xkzj8g-nixos-manpages_fish-completions.drv': 1 dependencies couldn't be built
cannot build derivation '/nix/store/3wwr04h32wnzcsv0yw9nhjqkgm02aqnh-nixos-manual-html_fish-completions.drv': 1 dependencies couldn't be built
cannot build derivation '/nix/store/dqiqy3qifhjws1j6ixrhq14h6lajz3sn-system-path.drv': 1 dependencies couldn't be built
cannot build derivation '/nix/store/asn49pd3fpn42ma6q05lirwcywld6v4q-nixos-system-kong-20.03.git.14844543bb9.drv': 1 dependencies couldn't be built
error: build of '/nix/store/asn49pd3fpn42ma6q05lirwcywld6v4q-nixos-system-kong-20.03.git.14844543bb9.drv' failed

Issues with the Home Manager manual

The following lines will refer to it extensively:

cannot build derivation '/nix/store/qahlw40w6ysf5nq27af12v0gmxi8xmq6-nixos-manpages.drv': 1 dependencies couldn't be built
cannot build derivation '/nix/store/5gy6h3sgj6nwajp72d5lkksnjahy1ljw-home-environment-manpages.drv': 1 dependencies couldn't be built
cannot build derivation '/nix/store/gi89iw2zrw4djrc8cnhgqys56agiha15-home-manager-path.drv': 1 dependencies couldn't be built
cannot build derivation '/nix/store/jp2sxpsx36sgwrvjif4bsiyr8vcs6nds-home-manager-generation.drv': 1 dependencies couldn't be built
error: build of '/nix/store/jp2sxpsx36sgwrvjif4bsiyr8vcs6nds-home-manager-generation.drv' failed

Again, either using an unstable channel or an issue with Home Manager. I found @flokli 's solution the best in Home Manager issue #254 to set

manual.manpages.enable = false;

in ~/.config/nixpkgs/home.nix (or /etc/nixos/configuration.nix in the home-manager.users.<username> block if you are managing home.nix in configuration.nix).

nixos-unstable, nixos-unstable-small, nixos-20.09 and nixos-20.09-small all have NixOS manual in the constituents so the channels should not advance if the manual fails to build, if I understand it correctly.

The manual failing to build is always an error but you should not encounter it unless you use nixpkgs-unstable channel or even master branch.

If you see such error, try to check what channels you use and upgrade them to the latest commit, where they might be already fixed. Otherwise, open an issue with the exact error and information about the channels you use.

1 Like

I’m all for trying to build the new config without failures, but (1) I don’t even know how to properly report issues (not to mention the anxiety that this involves), and (2) sometimes one really just needs to get things running and continue working. Finally (3), I’ve been using nix for years and it is still feels magic to me; when I try to reason about how all its components work, the word “chaos-yarn” pops into my mind…

1 Like

I feel you. IMO, the solution is to recognize that the issue does not have to be perfect. Just provide the information you think would be necessary to debug the problem and you will be fine. If we need more information, we will request it, no big deal.

I would recommend at least:

  1. The command you ran.
  2. The error message you got (running the command with --show-trace).
  3. The output of nix-shell -p nix-info --run "nix-info -m" (as mentioned in the bug report template on GitHub)

Relevant part of your NixOS configuration might be useful as well but if you are not sure which is relevant, triagers can help you (or you can ask here or on IRC).

Great that we have rollbacks.

It gets lot less magical if you avoid channels and weird magic flags like --upgrade and manage all the dependencies yourself. Before switching to flakes, I pointed nixpkgs in NIX_PATH to ~/Projects/nixpkgs and periodically fetched the nixos-unstable branch and rebuilt system on top of that.

Flakes or niv are even better since you can store the version of nixpkgs in your configuration git repo but using a nixpkgs checkout on your computer is convenient since you can modify it and test your changes immediately. (I still sometimes override the nixpkgs flake in my configuration repo to point to my nixpkgs checkout for this purpose.)

1 Like

Given the huge number of open issues, I am reluctant to add more unless I am confident that it will be useful, rather than merely distracting noise which wastes the developers’ time. Therefore I feel the obligation to

  1. be absolutely sure that it’s not just my ignorance or stupidity that is causing the problem
  2. search whether the issue I am raising has already been reported somewhere

My ignorance and stupidity, by definition, make me unqualified to judge about 1; the search in 2. just seems like an impossible task, so I end up doing something else with my time.

1 Like

The number of open issues is still quite small for a project the scope of Nixpkgs so I would not worry about it. If it is a legitimate bug, project will benefit from you opening the issue – people with the ability to fix the bug cannot really fix it unless they notice it, and opening an issue might bring it to their attention sooner.

And if it is caused by your ignorance, there is a good chance somebody else will have the same experience. So opening an issue and getting a resolution might help other people sharing the ignorance.

Sure, you should always attempt to resolve the problem yourself, at minimum by trying to search for parts of the error message, but if you fail, the community is there to help you.

2 Likes