kovidgoyal/kitty · warning

Failed to enable transparency. This happens when your deskto

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.

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)

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
• {panel args parse error}
• Failed to change panel configuration for OS Window {os_windo
• Failed to start tab drag: {e}

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