diff --git a/doc/languages-frameworks/qt.section.md b/doc/languages-frameworks/qt.section.md
index 6da0d7b501e9..9b3d1e054a62 100644
--- a/doc/languages-frameworks/qt.section.md
+++ b/doc/languages-frameworks/qt.section.md
@@ -29,9 +29,9 @@ Any Qt package should include `wrapQtAppsHook` or `wrapQtAppsNoGuiHook` in `nati
 
 ::: {.note}
 
-`wrapQtAppsHook` propagates plugins and QML components from `qtwayland` to ensure the Wayland platform plugin is available, which is required for graphical applications to run under Wayland on non-Qt based desktops. On platforms that do not support `qtwayland` (e.g. Darwin), only plugins `qtbase` will be propagated.
+`wrapQtAppsHook` propagates plugins and QML components from `qtwayland` on platforms that support it, to allow applications to act as native Wayland clients. It should be used for all graphical applications.
 
-`wrapQtAppsNoGuiHook` does not propagate `qtwayland` reduce closure size for purely command-line applications.
+`wrapQtAppsNoGuiHook` does not propagate `qtwayland` to reduce closure size for purely command-line applications.
 
 :::
 
diff --git a/pkgs/development/libraries/qt-6/hooks/qtbase-setup-hook.sh b/pkgs/development/libraries/qt-6/hooks/qtbase-setup-hook.sh
index 4057a3c67eed..48beac0b04fa 100644
--- a/pkgs/development/libraries/qt-6/hooks/qtbase-setup-hook.sh
+++ b/pkgs/development/libraries/qt-6/hooks/qtbase-setup-hook.sh
@@ -77,7 +77,10 @@ else # Only set up Qt once.
     qtPreHook() {
         # Check that wrapQtAppsHook/wrapQtAppsNoGuiHook is used, or it is explicitly disabled.
         if [[ -z "$__nix_wrapQtAppsHook" && -z "$dontWrapQtApps" ]]; then
-            echo >&2 "Error: neither wrapQtAppsHook nor wrapQtAppsNoGuiHook are used, and dontWrapQtApps is not set either."
+            echo >&2 "Error: this derivation depends on qtbase, but no wrapping behavior was specified."
+            echo >&2 "  - If this is a graphical application, add wrapQtAppsHook to nativeBuildInputs"
+            echo >&2 "  - If this is a CLI application, add wrapQtAppsNoGuiHook to nativeBuildInputs"
+            echo >&2 "  - If this is a library or you need custom wrapping logic, set dontWrapQtApps = true"
             exit 1
         fi
     }