What causes "could not load configuration" in LGUG2Z/komorebi?

Create a valid komorebi.json at ~/.config/komorebi/komorebi.json or generate one with `komorebi-bar`/docs sample

could not load configuration

Error message

could not load configuration

What it means

In main, when no static configuration was loaded at startup, komorebi spawns a thread running load_configuration().expect(...). If load_configuration returns Err (config file missing/unparseable), the spawned thread panics with 'could not load configuration' and the window manager starts without any user configuration (or hangs forever in the await_configuration backoff loop).

Source

Thrown at komorebi/src/main.rs:304

    } else {
        Arc::new(Mutex::new(WindowManager::new(
            winevent_listener::event_rx(),
            None,
        )?))
    };

    wm.lock().init()?;

    if let Some(config) = &static_config {
        StaticConfig::postload(config, &wm)?;
    }

    if !opts.await_configuration && !INITIAL_CONFIGURATION_LOADED.load(Ordering::SeqCst) {
        INITIAL_CONFIGURATION_LOADED.store(true, Ordering::SeqCst);
    };

    if static_config.is_none() {
        std::thread::spawn(|| load_configuration().expect("could not load configuration"));

        if opts.await_configuration {
            let backoff = Backoff::new();
            while !INITIAL_CONFIGURATION_LOADED.load(Ordering::SeqCst) {
                backoff.snooze();
            }
        }
    }

    let dumped_state = temp_dir().join("komorebi.state.json");

    if !opts.clean_state && dumped_state.is_file() {
        if let Ok(state) = serde_json::from_str(&std::fs::read_to_string(&dumped_state)?) {
            wm.lock().apply_state(state);
        } else {
            tracing::warn!(
                "cannot apply state from {}; state struct is not up to date",
                dumped_state.display()

View on GitHub (pinned to e0709f02bf)

Solutions

Create a valid komorebi.json at ~/.config/komorebi/komorebi.json or generate one with `komorebi-bar`/docs sample
Set KOMOREBI_CONFIG_HOME to a directory that contains komorebi.json
Validate the JSON (schema check / jq .) and fix schema violations
If you intentionally run configless, ensure the config path resolution logic finds nothing but load_configuration handles that gracefully rather than erroring

Example fix

// before
std::thread::spawn(|| load_configuration().expect("could not load configuration"));
// after
std::thread::spawn(|| {
    if let Err(e) = load_configuration() {
        tracing::error!("could not load configuration: {e}");
    }
});

Defensive patterns

Strategy: validation

Validate before calling

let path = std::env::var("KOMOREBI_CONFIG_HOME")
    .map(std::path::PathBuf::from)
    .unwrap_or_else(|_| dirs::home_dir().unwrap().join(".config/komorebi"));
let cfg = path.join("komorebi.json");
assert!(cfg.exists(), "config missing at {cfg:?}");
let _: serde_json::Value = serde_json::from_str(&std::fs::read_to_string(cfg).unwrap())
    .expect("config is not valid JSON");

Prevention

Validate komorebi.json with the published JSON schema after every edit
Set KOMOREBI_CONFIG_HOME explicitly and confirm the file exists before launch
Start from the official sample config rather than a blank file

When it happens

Trigger: StaticConfig is None at startup and load_configuration() fails: komorebi.json absent from $HOME/.config/komorebi or $KOMOREBI_CONFIG_HOME, path set but unreadable, or JSON contains schema-invalid values.

Common situations: First install without a komorebi.json; KOMOREBI_CONFIG_HOME pointing to a nonexistent directory; a typo'd or schema-invalid config after upgrading komorebi.

Understand the failure class

Background: "Config file not found": what it means and how to fix it in docker-sync, Maven, Vagrant, Turborepo and other tools — this error's family across 60 libraries.

Related errors

AI-assisted analysis of LGUG2Z/komorebi@e0709f02bf (2026-09-06). Data as JSON: /api/errors/eec071f7e35ce810. Report an issue: GitHub.