diff --git a/nixos/doc/manual/man-nixos-rebuild.xml b/nixos/doc/manual/man-nixos-rebuild.xml
index b2ca9f457a2..ea96f49fa97 100644
--- a/nixos/doc/manual/man-nixos-rebuild.xml
+++ b/nixos/doc/manual/man-nixos-rebuild.xml
@@ -548,6 +548,14 @@
       (<replaceable>user@host</replaceable>). You can also set ssh options by
       defining the <envar>NIX_SSHOPTS</envar> environment variable.
      </para>
+
+     <para>
+      Note that <command>nixos-rebuild</command> honors the
+      <literal>nixpkgs.crossSystem</literal> setting of the given configuration
+      but disregards the true architecture of the target host. Hence the
+      <literal>nixpkgs.crossSystem</literal> setting has to match the target
+      platform or else activation will fail.
+     </para>
     </listitem>
    </varlistentry>
 
diff --git a/nixos/modules/system/activation/switch-to-configuration.pl b/nixos/modules/system/activation/switch-to-configuration.pl
index 9e5b760434a..3f0d976e70b 100755
--- a/nixos/modules/system/activation/switch-to-configuration.pl
+++ b/nixos/modules/system/activation/switch-to-configuration.pl
@@ -1,5 +1,17 @@
 #! @perl@/bin/perl
 
+# Issue #166838 uncovered a situation in which a configuration not suitable
+# for the target architecture caused a cryptic error message instead of
+# a clean failure. Due to this mismatch, the perl interpreter in the shebang
+# line wasn't able to be executed, causing this script to be misinterpreted
+# as a shell script.
+#
+# Let's detect this situation to give a more meaningful error
+# message. The following two lines are carefully written to be both valid Perl
+# and Bash.
+printf "Perl script erroneously interpreted as shell script,\ndoes target platform match nixpkgs.crossSystem platform?\n" && exit 1
+    if 0;
+
 use strict;
 use warnings;
 use Config::IniFiles;