wezterm/wezterm · error

{}

Error message

{}

What it means

wezterm::config::configuration_result() (config/src/lib.rs:459) is the umbrella surface for 'your config failed to load': the Lua config is evaluated lazily, and if evaluation produced an error (syntax error, runtime error, invalid option value) the error is stored on the global CONFIG and re-raised here as bail!("{}", error). The message body is whatever the config loader recorded — typically a Lua error with file/line information. Hitting it means the config handle you asked for was never built.

Solutions

1. Read the embedded message — it carries the original Lua error including chunk name and line number; fix that location first.
2. Reproduce from a shell without the GUI: run any `wezterm` CLI subcommand (e.g. `wezterm show-keys`) — it loads the config and prints the same error to stderr.
3. Bisect by commenting out recently changed sections, especially event callbacks and plugin requires.
4. After a version upgrade, check the changelog/docs for renamed options; update or pin plugins whose API calls no longer exist.

Example fix

-- before (wezterm.lua)
local wezterm = require 'wezterm'
wezterm.nonexistent_function() -- runtime error: attempt to call a nil value
return {}

-- after
local wezterm = require 'wezterm'
return {}

# CI / shell: any CLI subcommand loads the config and exits non-zero on error
wezterm show-keys --lua > /dev/null || { echo 'config failed to load'; exit 1; }

let config = match wezterm::config::configuration_result() {
    Ok(handle) => handle,
    Err(err) => {
        log::error!("config failed to load: {err:#}");
        // fall back to last-good handle or defaults instead of propagating
        return;
    }
};

When it happens

Trigger: A syntax error in wezterm.lua or a required config file; calling a nonexistent WezTerm API (e.g. wezterm.some_misspelled_fn()); passing a wrong-typed option value; `--config key=value` overrides whose RHS evaluates to nil; a plugin that requires a newer WezTerm version.

Common situations: Editing the config and introducing a typo; upgrading WezTerm across releases where options were renamed or removed; a plugin update that calls APIs not present in the installed binary.

Related errors

• invalid keycode
• Attempted to set invalid config option
• cannot register module
• cannot register module wezterm.
• with name " " conflicts with another existing with the same…

AI-assisted analysis of wezterm/wezterm@3ff7522b96 (2026-08-20). Data as JSON: /api/errors/69396dc400444a26. Report an issue: GitHub.

Appendix: source

Thrown at config/src/lib.rs:459

pub fn configuration() -> ConfigHandle {
    CONFIG.get()
}

/// Returns a version of the config (loaded from the config file)
/// with some field overridden based on the supplied overrides object.
pub fn overridden_config(overrides: &wezterm_dynamic::Value) -> Result<ConfigHandle, Error> {
    CONFIG.overridden(overrides)
}

pub fn reload() {
    CONFIG.reload();
}

/// If there was an error loading the preferred configuration,
/// return it, otherwise return the current configuration
pub fn configuration_result() -> Result<ConfigHandle, Error> {
    if let Some(error) = CONFIG.get_error() {
        bail!("{}", error);
    }
    Ok(CONFIG.get())
}

/// Returns the combined set of errors + warnings encountered
/// while loading the preferred configuration
pub fn configuration_warnings_and_errors() -> Vec<String> {
    CONFIG.get_warnings_and_errors()
}

struct ConfigInner {
    config: Arc<Config>,
    error: Option<String>,
    warnings: Vec<String>,
    generation: usize,
    watcher: Option<notify::RecommendedWatcher>,
    subscribers: HashMap<usize, Box<dyn Fn() -> bool + Send>>,
}

View on GitHub (pinned to 3ff7522b96)