kovidgoyal/kitty · warning

Failed to enable transparency. This happens when your…

Error message

Failed to enable transparency. This happens when your desktop environment does not support compositing.

What it means

Kitty requested a semi-transparent background (background_opacity < 1.0) but the window system reported the window is not actually composited with alpha support. This occurs when the desktop environment lacks a compositing manager or the window is created in a mode where transparency cannot be honored (e.g. certain X11 setups without a compositor running). It is logged once (static warned flag) because every window creation would otherwise repeat it.

Solutions

1. Start a compositor (e.g. run picom, or enable compositing in your WM/desktop settings) and restart kitty
2. Set background_opacity 1.0 in kitty.conf to acknowledge opacity is unsupported
3. On Wayland, ensure a compositor that supports alpha (most do); check you are not forcing X11 via GLFW_PLATFORM or XDG_SESSION_TYPE
4. If using a tiling WM, add picom to your startup script

Example fix

# before (kitty.conf)
background_opacity 0.85
# after
background_opacity 1.0
# or start a compositor before kitty:
picom -b & kitty

# shell check before launching kitty with transparency
if [ "$XDG_SESSION_TYPE" = "x11" ] && ! pgrep -x picom >/dev/null && ! pgrep -x compton >/dev/null; then
  sed -i 's/^background_opacity .*/background_opacity 1.0/' ~/.config/kitty/kitty.conf
fi

When it happens

Trigger: Setting background_opacity to a value < 1.0 in kitty.conf while running on X11 without a compositor (no picom/xfwm compositing), or on a framebuffer/headless session, or with --override background_opacity=0.9 on an environment where is_semi_transparent evaluates false at window creation.

Common situations: Starting kitty on a minimal X11 WM (i3, dwm) without picom/compton running; running kitty inside some VNC or Xephyr sessions; WSLg edge cases; users copying configs with background_blur + background_opacity to machines without compositing.

Related errors

• Failed to load glfwGetX11Display
• Creating desktop panels is not supported on this platform
• Failed to change panel configuration for OS Window
• Failed to start tab drag
• Failed to start window drag

AI-assisted analysis of kovidgoyal/kitty@6d5d0c4406 (2026-08-27). Data as JSON: /api/errors/2fb9b652a65c5ce4. Report an issue: GitHub.

Appendix: source

Thrown at kitty/glfw.c:2271

    glfwSetCursorPosCallback(glfw_window, cursor_pos_callback);
    glfwSetCursorEnterCallback(glfw_window, cursor_enter_callback);
    glfwSetScrollCallback(glfw_window, scroll_callback);
    glfwSetKeyboardCallback(glfw_window, key_callback);

    glfwSetDragSourceCallback(glfw_window, drag_source_callback);
    glfwSetDropEventCallback(glfw_window, drop_dest_callback);
    monotonic_t now = monotonic();
    w->is_focused = true;
    w->shader_anim_event_registry |= (1u << SHADER_ANIM_EVENT_OS_WINDOW_FOCUS_IN) | (1u << SHADER_ANIM_EVENT_WINDOW_FOCUS_IN);
    w->cursor_blink_zero_time = now;
    w->last_mouse_activity_at = now;
    w->mouse_activate_deadline = -1;
    w->mouse_show_threshold = 0;
    w->background_opacity.supports_transparency = is_semi_transparent;
    if (want_semi_transparent && !w->background_opacity.supports_transparency) {
        static bool warned = false;
        if (!warned) {
            log_error("Failed to enable transparency. This happens when your desktop environment does not support compositing.");
            warned = true;
        }
    }
    init_window_chrome_state(&w->last_window_chrome, OPT(background), effective_os_window_alpha(w));
    if (w->is_layer_shell) {
        if (global_state.is_apple) set_layer_shell_config_for(w, lsc);
    } else apply_window_chrome_state(w->handle, w->last_window_chrome, width, height, global_state.is_apple ? OPT(hide_window_decorations) != 0 : false);
#ifdef __APPLE__
    if (!w->is_layer_shell) glfwCocoaSetWindowLevel(w->handle, OPT(macos_ns_window_layer));
#endif
    // Update window state
    // We do not call glfwWindowHint to set GLFW_MAXIMIZED before the window is created.
    // That would cause the window to be set to maximize immediately after creation and use the wrong initial size when restored.
    if (window_state != WINDOW_NORMAL) change_state_for_os_window(w, window_state);
#ifdef __APPLE__
    // macOS: Show the window after it is ready
    if (window_state != WINDOW_HIDDEN) glfwShowWindow(glfw_window, false);
#endif

View on GitHub (pinned to 6d5d0c4406)