From 396358dc08f4bd1c19e2b9f8ea7a5850e34f7845 Mon Sep 17 00:00:00 2001
From: Tucker Shea <tucker@tuckershea.com>
Date: Mon, 22 Dec 2025 11:01:04 -0500
Subject: [PATCH] fix: make --rebuild failures actionable

See #8188. Resolves issues about the error not
being actionable, but I am not marking it closing
yet because of further discussion about the naming
of these flags in the thread.

`nix build --rebuild` (and others)
will fail if the derivation has not been built
before, because it runs a check build and
confirms that the build was deterministic.

It may be unclear to users that --rebuild will fail
if the derivation has never been built before,
because the flag makes no indication that a
determinism check occurs.

The error message does
not help clear this up, or provide any actionable
steps, and at first glance seems to indicate that
the derivation being built is invalid, rather than
just not present in the store:

```
error: some outputs of '...' are not valid, so checking is not possible
```

We can suggest to the user the following (correct)
rewrites. This list of commands that may result in
the error is comprehensive.

- `nix build --rebuild` to `nix build` or `nix build --repair`
- `nix-build --check` to `nix-build` or `nix-build --repair`
- `nix-store --realise --check` to `nix-store --realise` or `nix-store --realise --repair`

Wording is based on that in the documentation:

```
(nix build)
--repair During evaluation, rewrite missing or
         corrupted files in the Nix store. During
         building, rebuild missing or corrupted
         store paths.

(nix-build)
--repair Fix corrupted or missing store paths by
         redownloading or rebuilding them. Note
         that this is slow because it requires
         computing a cryptographic hash of the
         contents of every path in the closure
         of the build. Also note the warning
         under nix-store --repair-path.

(nix-store --realise)
--repair Fix corrupted or missing store paths by
         redownloading or rebuilding them. (etc)
```
---
 src/libstore/build/derivation-goal.cc | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/src/libstore/build/derivation-goal.cc b/src/libstore/build/derivation-goal.cc
index bdbca5f00..e92fa25f3 100644
--- a/src/libstore/build/derivation-goal.cc
+++ b/src/libstore/build/derivation-goal.cc
@@ -154,7 +154,9 @@ Goal::Co DerivationGoal::haveDerivation(bool storeDerivation)
         }
         if (buildMode == bmCheck && !allValid)
             throw Error(
-                "some outputs of '%s' are not valid, so checking is not possible",
+                "some outputs of '%s' are not valid, so checking is not possible\n"
+                "Hint: --rebuild and --check error if the derivation was not previously built and cannot be substituted.\n"
+                "      Remove it to perform a fresh build, or use --repair to rewrite missing or corrupted builds in the store.",
                 worker.store.printStorePath(drvPath));
     }