diff --git a/kitty/config.py b/kitty/config.py
index b4c51b7cf..015cfefb2 100644
--- a/kitty/config.py
+++ b/kitty/config.py
@@ -558,4 +558,7 @@ def finalize_keys(opts):
 def load_config(*paths, overrides=None):
     opts = _load_config(Options, defaults, parse_config, merge_configs, *paths, overrides=overrides)
     finalize_keys(opts)
+    if opts.background_opacity < 1.0 and opts.macos_titlebar_color:
+        log_error('Cannot use both macos_titlebar_color and background_opacity')
+        opts.macos_titlebar_color = 0
     return opts
diff --git a/kitty/kitty.conf b/kitty/kitty.conf
index b64099eb4..6e7ae08e3 100644
--- a/kitty/kitty.conf
+++ b/kitty/kitty.conf
@@ -507,7 +507,11 @@ clear_all_shortcuts no
 # Change the color of the kitty window's titlebar on macOS. A value of "system"
 # means to use the default system color, a value of "background" means to use
 # the default background color and finally you can use an arbitrary color, such
-# as #12af59 or "red".
+# as #12af59 or "red". WARNING: This option works by using a hack, as there is
+# no proper Cocoa API for it. It sets the background color of the entire window
+# and makes the titlebar transparent. As such it is incompatible with
+# background_opacity. If you want to use both, you are probably better off just
+# hiding the titlebar with macos_hide_titlebar.
 macos_titlebar_color system
 
 # Hide the kitty window's title bar on macOS.