jdx/mise · error

mise completion metadata should parse

Error message

mise completion metadata should parse

What it means

`completion_spec()` parses the statically embedded `src/assets/mise-extra.usage.kdl` file at runtime via `include_str!`. Because the file ships with the binary, a parse failure means the checked-in asset is malformed — this `.expect()` turns that into a panic to surface the drift immediately.

Source

Thrown at src/cli/usage.rs:78

        // let a global shadow a same-named task flag, dropping its choices (mise#11282),
        // and fail outright on `mise run --force <task>`. 3.5 was required for the zsh
        // colon completion fixes for task names and insert strings (jdx/usage#666,
        // jdx/usage#670).
        // Declare what each command does to the world. clap cannot express this,
        // so it is applied to the derived spec; see command_effects.
        crate::cli::command_effects::apply(&mut spec);

        spec.restamp();

        spec
    }
}

pub(super) fn completion_spec() -> usage::Spec {
    let mut spec = spec();
    let extra: usage::Spec = include_str!("../assets/mise-extra.usage.kdl")
        .parse()
        .expect("mise completion metadata should parse");
    spec.merge(extra);
    spec
}

impl Usage {
    pub(crate) fn run(self) -> Result<()> {
        // 3.6 added `effect=` (jdx/usage#739), 4.0 added it on flags and args
        // (jdx/usage#742), and 6.6 added flags scoped to implicit clauses
        // (jdx/usage#1343). 6.8 adds mount synopsis metadata (jdx/usage#1393).
        // Older `usage` CLIs reject the spec outright, so this
        // moves in lockstep with the fields and layouts the spec actually carries.
        let min_version = r#"min_usage_version "6.8""#;
        println!("{min_version}\n{}", completion_spec().to_string().trim());
        Ok(())
    }
}

#[cfg(test)]

View on GitHub (pinned to afd2eddd3a)

Solutions

1. Validate the KDL with a parser: change the file, then run `mise run build && target/debug/mise usage` to reproduce and fix the syntax error
2. Restore the pristine asset from git: `git checkout HEAD -- src/assets/mise-extra.usage.kdl`
3. If it appeared after a dependency update, align the asset syntax with the new parser requirements
4. Reinstall mise from an official release if your local copy is corrupted

Example fix

// before (mise-extra.usage.kdl)
root flag "--raw" "-r" help="Raw output" arg("value") optional
// after (valid KDL node form)
flag "--raw" "-r" help="Raw output" {
    arg value
    optional
}

# Validate the asset parses after editing it:
cargo build && target/debug/mise usage > /dev/null && echo OK

When it happens

Trigger: `mise-extra.usage.kdl` corrupted or hand-edited with invalid KDL syntax; a KDL schema change in the usage parser no longer accepted by the older asset (or vice versa after a dependency bump); build tooling mangling the asset.

Common situations: Contributors editing completion metadata directly with a syntax mistake; merge conflicts in the asset resolved incorrectly; users only hit this on broken dev builds or corrupted installs.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• generated mise usage spec
• GitHub API URL should be valid
• GitHub API URL should support path segments
• task executor initialized
• executor must be initialized before running tasks

AI-assisted analysis of jdx/mise@afd2eddd3a (2026-09-09). Data as JSON: /api/errors/3cd88320ef84213a. Report an issue: GitHub.