zed-industries/zed · error

libxkbcommon failed to create an XKB context

Error message

libxkbcommon failed to create an XKB context

What it means

Guard in validate_xkb_context: libxkbcommon returned a null/invalid xkb_context, so keyboard mapping, key event translation, and IME cannot be initialized for the Wayland/X11 backend. Fires when libxkbcommon is missing, too old, or cannot allocate its context (e.g. broken XKB data files in /usr/share/xkb).

Source

Thrown at crates/gpui_linux/src/linux/platform.rs:913

#[cfg(any(feature = "wayland", feature = "x11"))]
pub(super) fn is_within_click_distance(a: Point<Pixels>, b: Point<Pixels>) -> bool {
    let diff = a - b;
    diff.x.abs() <= DOUBLE_CLICK_DISTANCE && diff.y.abs() <= DOUBLE_CLICK_DISTANCE
}

/// Creates an XKB context for keymaps supplied by Wayland or X11.
///
/// Server keymaps are already resolved and need no local keyboard definitions.
/// Loading default include paths can fail on systems without those files.
#[cfg(any(feature = "wayland", feature = "x11"))]
pub(super) fn new_xkb_context() -> anyhow::Result<xkb::Context> {
    validate_xkb_context(xkb::Context::new(xkb::CONTEXT_NO_DEFAULT_INCLUDES))
}

#[cfg(any(feature = "wayland", feature = "x11"))]
fn validate_xkb_context(context: xkb::Context) -> anyhow::Result<xkb::Context> {
    ensure!(
        !context.get_raw_ptr().is_null(),
        "libxkbcommon failed to create an XKB context"
    );
    Ok(context)
}

#[cfg(any(feature = "wayland", feature = "x11"))]
pub(super) fn get_xkb_compose_state(cx: &xkb::Context) -> Option<xkb::compose::State> {
    let mut locales = Vec::default();
    if let Some(locale) = env::var_os("LC_CTYPE") {
        locales.push(locale);
    }
    locales.push(OsString::from("C"));
    let mut state: Option<xkb::compose::State> = None;
    for locale in locales {
        if let Ok(table) =
            xkb::compose::Table::new_from_locale(cx, &locale, xkb::compose::COMPILE_NO_FLAGS)
        {

View on GitHub (pinned to 9d272b0363)

Solutions

1. Install or upgrade libxkbcommon and verify /usr/share/xkb keymap data exists
2. Check XDG_DATA_DIRS / XKB_CONFIG_ROOT overrides that hide xkbcommon's data files
3. Propagate the error so the platform reports keyboard initialization failure instead of proceeding with a null context

When it happens

Trigger: Thrown at crates/gpui_linux/src/linux/platform.rs:847 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of zed-industries/zed@9d272b0363 (2026-08-20). Data as JSON: /api/errors/9c06f6489975dfba. Report an issue: GitHub.