From c0da60564f2b2432b4d67ea084e76b718a54137f Mon Sep 17 00:00:00 2001
From: phaer <phaer@phaer.org>
Date: Wed, 26 Nov 2025 01:14:01 +0100
Subject: [PATCH] system.build.images: warn if system.build.image is defined...

but still define the images (plural) options. If both are used,
conflicts due to colliding priorities will pop up, but if we just
skip defining `system.build.images`, users of e.g.
`nixos-rebuild build-image` will receive confusing error messages.

With this change, they'll see the evaluation warning, providing
import context for the errors below the warning.
---
 nixos/modules/image/images.nix | 44 ++++++++++++++++++++--------------
 1 file changed, 26 insertions(+), 18 deletions(-)

diff --git a/nixos/modules/image/images.nix b/nixos/modules/image/images.nix
index b0f86ed5c455..b8729e6e3e6a 100644
--- a/nixos/modules/image/images.nix
+++ b/nixos/modules/image/images.nix
@@ -81,22 +81,30 @@ in
     };
   };
 
-  config.image.modules = lib.mkIf (!config.system.build ? image) imageModules;
-  config.system.build.images = lib.mkIf (!config.system.build ? image) (
-    lib.mapAttrs (
-      name: nixos:
-      let
-        inherit (nixos) config;
-        inherit (config.image) filePath;
-        builder =
-          config.system.build.image
-            or (throw "Module for `system.build.images.${name}` misses required `system.build.image` option.");
-      in
-      lib.recursiveUpdate builder {
-        passthru = {
-          inherit config filePath;
-        };
-      }
-    ) imageConfigs
-  );
+  config.image.modules = imageModules;
+  config.system.build.images =
+    lib.warnIf (config.system.build ? image)
+      ''
+        `system.build.image` is defined, while `system.build.images` is used.
+        The former will conflict with variants in the latter.
+        Maybe you are importing an image-building module into the toplevel?
+        Add it to `image.modules` instead, or adjust priorities manually.
+      ''
+      (
+        lib.mapAttrs (
+          name: nixos:
+          let
+            inherit (nixos) config;
+            inherit (config.image) filePath;
+            builder =
+              config.system.build.image
+                or (throw "Module for `system.build.images.${name}` misses required `system.build.image` option.");
+          in
+          lib.recursiveUpdate builder {
+            passthru = {
+              inherit config filePath;
+            };
+          }
+        ) imageConfigs
+      );
 }