What causes "Failed to load metadata for mod '{}': {}" in ramensoftware/windhawk?

Inspect the mod directory named in the warning; fix or restore its metadata file.

Failed to load metadata for mod

Error message

Failed to load metadata for mod '{}': {}

What it means

warn_load_errors in windhawk-core CLI (commands/mod.rs) emits a stderr warning for each installed mod whose metadata failed to load, shared by `mod list` and `repo list` so wording stays consistent. It is not a thrown error: the listing continues, but the message flags that some mods will be missing or incomplete in the output because their metadata could not be parsed/loaded.

Solutions

Inspect the mod directory named in the warning; fix or restore its metadata file.
Reinstall the affected mod so its metadata is regenerated from a good source.
If the format changed, upgrade (or reinstall at matching version) so the CLI's parser matches the metadata on disk.
Remove the broken mod entry if it is no longer needed, then re-run the listing.

Defensive patterns

Strategy: validation

Validate before calling

// before running `wh-cli mod list`, verify metadata parses:
for m in ~/.local/share/windhawk/mods/*/; do
  test -f "$m/metadata.h" || echo "missing metadata: $m"
done

Prevention

Uninstall mods only through the CLI/app so metadata is removed cleanly.
Keep Windhawk and its mods at compatible versions to avoid metadata format drift.
Avoid hand-editing mod metadata files.
Reinstall any mod reported in load_errors before relying on `mod list` output.

When it happens

Trigger: ListInstalledModsResult.load_errors is non-empty after enumerating installed mods: a mod's metadata file is missing, corrupted, or fails schema/version parsing during `wh-cli mod list` or `repo list`.

Common situations: A partially uninstalled or manually edited mod directory; metadata format changed between Windhawk versions leaving older files unparsable; interrupted write leaving truncated metadata on disk.

Related errors

AI-assisted analysis of ramensoftware/windhawk@61d99ed8e1 (2026-09-12). Data as JSON: /api/errors/9cb219e6045c48c0. Report an issue: GitHub.

Appendix: source

Thrown at src/windhawk-core/cli/src/commands/mod.rs:49

pub(crate) fn language(settings: &AppSettings) -> String {
    if settings.language.is_empty() {
        "en".to_owned()
    } else {
        settings.language.clone()
    }
}

/// Whether update checks are enabled (`!disableUpdateCheck`), gating the
/// installed-state update flag, mirroring the GUI.
pub(crate) fn check_for_updates(settings: &AppSettings) -> bool {
    !settings.disable_update_check
}

/// Emit a stderr warning for each mod whose metadata failed to load, shared by
/// `mod list` and `repo list` so the two listings cannot drift in the wording.
pub(crate) fn warn_load_errors(env: &Environment, result: &ListInstalledModsResult) {
    for load_error in &result.load_errors {
        env.logger.warn(&format!(
            "Failed to load metadata for mod '{}': {}",
            load_error.mod_id, load_error.error
        ));
    }
}

View on GitHub (pinned to 61d99ed8e1)