jdx/mise · error

mise cannot derive completions from a {format} spec

Error message

mise cannot derive completions from a {format} spec

What it means

mise can only auto-derive a shell completion script from a CLI specification in the `usage` format, because it shells out to usage's own completion tooling. When a packslip's cli-spec resource names any other format (e.g. clap_complete, cobra, custom JSON), derive_from_spec refuses to guess how to turn it into a completion script and bails. The error is collected per-source and usually surfaces wrapped inside the 'no usable <shell> completion' aggregate error.

Source

Thrown at src/packslip.rs:1099

        .envs(env)
        .prepend_path(vec![install_path.join(MISE_BINS_DIR)])?
        .current_dir(work.path())
        .stdin(std::process::Stdio::null())
        .stderr(std::process::Stdio::null())
        .with_timeout(timeout)
        .read_isolated(4 * 1024 * 1024)
        .await?;
    if output.trim().is_empty() {
        bail!("resource command produced no output");
    }
    Ok(output)
}

/// Derive a completion script from a CLI spec with the consumer's own
/// tooling. Only the `usage` format is known.
fn derive_from_spec(format: &str, bin: &str, spec: &Path, shell: &str) -> Result<String> {
    if format != "usage" {
        bail!("mise cannot derive completions from a {format} spec");
    }
    // Validate before returning a loader, so an invalid preferred spec still
    // falls through to another resource source.
    file::read_to_string(spec)?
        .parse::<usage::Spec>()
        .map_err(|err| eyre!("invalid usage specification: {err}"))?;
    let shell = usage_rs::complete::Shell::from_name(shell)
        .ok_or_else(|| eyre!("unsupported completion shell: {shell}"))?;
    let path = completions::encode_spec_path(spec);
    let script = usage_rs::script::script_for("mise", bin, shell);
    Ok(script.replace(
        " __complete_word__ ",
        &format!(" __usage_complete_word {path} "),
    ))
}

/// The `shell` completion script for `tool`, from the packslip of the
/// version that is active right now.

View on GitHub (pinned to afd2eddd3a)

Solutions

1. Check the tool's packslip statement for its cli-spec format; if it is not "usage", the source cannot be used by mise and another completion source (file or exec) must be declared.
2. If you author the packslip, change the format field to "usage" or add a separate completion file/exec source.
3. Run `mise completion <shell> --tool <tool>` again after fixing the packslip and reinstalling; verify with `mise packslip forget <project>` and reinstall if the statement is stale.

Example fix

// packslip statement — before
[[resource]]
type = "cli-spec"
format = "clap_complete"
// after
[[resource]]
type = "cli-spec"
format = "usage"

let format = packslip_cli_spec_format(tool); // from statement
if format != Some("usage") { eprintln!("cli-spec source unusable; expect fallback source"); }

fn is_usage_spec(format: &str) -> bool { format == "usage" }

match completion_script(&config, tool, shell) {
    Ok(script) => use(script),
    Err(e) if e.to_string().contains("cannot derive completions") => try_next_source(),
    Err(e) => return Err(e),
}

When it happens

Trigger: Calling `mise completion <shell> --tool <tool>` (or tab-completing a tool) where the tool's packslip declares a cli-spec completion source whose format string is anything other than "usage".

Common situations: Installing a tool via a packslip whose publisher generates specs in another format; a mis-authored packslip where the format field was typoed (e.g. "usge" or "clap"); a vendor switching spec formats between releases.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• skill asset {name} is not an archive mise can unpack
• invalid completion cache identity
• {} was not installed from a packslip, so mise does not know
• the packslip of {} declares a {shell} completion, but none o
• the packslip of {} declares no {shell} completion

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