diff --git a/docs/glossary.rst b/docs/glossary.rst
index fb96089e9..3c2b30d0f 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -64,6 +64,13 @@ Variables that influence kitty behavior
    Same as :envvar:`VISUAL`. Used if :envvar:`VISUAL` is not set.
 
 
+.. envvar:: KITTY_WAYLAND_DETECT_MODIFIERS
+
+   When set to a non-empty value, kitty attempts to autodiscover XKB
+   modifiers under Wayland. It is possible for the autodiscovery to
+   fail; the default Wayland XKB mappings are used in this case.
+
+
 Variables that kitty sets when running child programs
 
 .. envvar:: LANG
diff --git a/docs/keyboard-protocol.rst b/docs/keyboard-protocol.rst
index e884fafea..720009c34 100644
--- a/docs/keyboard-protocol.rst
+++ b/docs/keyboard-protocol.rst
@@ -145,8 +145,8 @@ Modifiers
 This protocol supports six modifier keys, :kbd:`shift, alt, ctrl, super, hyper
 and meta` as well as :kbd:`num_lock and caps_lock`. Here :kbd:`super` is either
 the *Windows/Linux* key or the *Cmd* key on mac keyboards. :kbd:`hyper` and
-:kbd:`meta` are typically present only on X11 based systems with special XKB
-rules. Modifiers are encoded as a bit field with::
+:kbd:`meta` are typically present only on X11/Wayland based systems with
+special XKB rules. Modifiers are encoded as a bit field with::
 
     shift     0b1         (1)
     alt       0b10        (2)
diff --git a/glfw/xkb_glfw.c b/glfw/xkb_glfw.c
index 24fa7c744..ac30e618e 100644
--- a/glfw/xkb_glfw.c
+++ b/glfw/xkb_glfw.c
@@ -515,15 +515,17 @@ static int local_modifier_mapping(_GLFWXKBData *xkb) {
         }
     }
 
+    if ( algorithm.failed )
+        debug( "Wayland modifier autodetection algorithm failed; using defaults\n" );
     return !algorithm.failed;
 }
 
 static void
 glfw_xkb_update_masks(_GLFWXKBData *xkb) {
     // Should find better solution under Wayland
-    // See https://github.com/kovidgoyal/kitty/pull/3430 for discussion
+    // See https://github.com/kovidgoyal/kitty/pull/3943 for discussion
 
-    if ( !local_modifier_mapping( xkb ) ) {
+    if ( getenv( "KITTY_WAYLAND_DETECT_MODIFIERS" ) == NULL || !local_modifier_mapping( xkb ) ) {
 #define S( a ) xkb->a##Idx = XKB_MOD_INVALID; xkb->a##Mask = 0
         S(hyper); S(meta);
 #undef S