jdx/mise · error

conflicting aqua var

Error message

conflicting aqua var `{key}`: use only one spelling

What it means

Aqua backend configuration allows specifying the same aqua variable under multiple spellings (e.g. different naming forms for the same option). insert_var_option detects that two spellings resolve to the same key and throws rather than silently letting one shadow the other, since the effective value would be ambiguous.

Solutions

1. Search your aqua package/config for duplicate variable definitions and keep only one spelling of each key
2. If overriding a built-in registry package, remove the var from your override instead of redefining it, or ensure the key names differ
3. Check recent config edits/diffs for an accidentally duplicated key

Example fix

# before (mise.toml)
[tools]
"aqua:suzuki-shunsuke/tfcmt" = { version = "4", vars = { wrap = true, wrap = false } }
# after
[tools]
"aqua:suzuki-shunsuke/tfcmt" = { version = "4", vars = { wrap = true } }

let mut seen = std::collections::HashSet::new();
for key in normalized_var_keys(&cfg) {
    if !seen.insert(key.clone()) {
        return Err(anyhow!("duplicate aqua var `{key}`: use only one spelling"));
    }
}

match insert_var_option(&mut map, key, value) {
    Err(e) if e.to_string().contains("conflicting aqua var") => warn_and_skip_or_fail(&key),
    r => r?,
}

When it happens

Trigger: An aqua registry/package config defines a var key that collides with another spelling of the same key when merging var options into the result map (result.contains_key(&key) is true).

Common situations: Hand-edited mise/aqua config listing an aqua var twice in different forms; merging a custom aqua registry override on top of a built-in package that already defines the var; copy-pasting package config with both legacy and new key spellings.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

• aqua package does not have repo_owner and/or repo_name.
• aqua var ` ` must be a string, got
• at least one bin path should exist
• github_content package requires `path`
• a provided source resolves to a path

AI-assisted analysis of jdx/mise@533346cc37 (2026-09-17). Data as JSON: /api/errors/1528231ed7704870. Report an issue: GitHub.

Appendix: source

Thrown at src/backend/aqua.rs:131

            }

            let key = if let Some(key) = key.strip_prefix("vars.") {
                key.to_string()
            } else {
                key.clone()
            };
            Self::insert_var_option(&mut vars, key, value)?;
        }
        Ok(vars)
    }

    fn insert_var_option<'b>(
        result: &mut BTreeMap<String, &'b toml::Value>,
        key: String,
        value: &'b toml::Value,
    ) -> Result<()> {
        if result.contains_key(&key) {
            bail!("conflicting aqua var `{key}`: use only one spelling");
        }
        result.insert(key, value);
        Ok(())
    }

    fn insert_nested_var_options<'b>(
        result: &mut BTreeMap<String, &'b toml::Value>,
        table: &'b toml::Table,
    ) -> Result<()> {
        for (key, value) in table {
            Self::insert_var_option(result, key.clone(), value)?;
        }
        Ok(())
    }
}

#[derive(Debug, Clone, PartialEq, Eq)]
struct AquaFileLink {

View on GitHub (pinned to 533346cc37)