rust-lang/cargo · error

invalid configuration for key `{}` {}

Error message

invalid configuration for key `{}`
{}

What it means

The internal helper GlobalContext::expected (mod.rs:1152-1156) wraps a typed config-value error (ConfigError::expected from error.rs) into 'invalid configuration for key `<key>`\n<detail>' when a config key holds a value of the wrong type. The second line carries the underlying '`<key>` expected X, but found a Y' detail plus the definition.

Source

Thrown at src/context/mod.rs:1155

    /// Low-level method for getting a config value as an `OptValue<HashMap<String, CV>>`.
    ///
    /// NOTE: This does not read from env. The caller is responsible for that.
    fn get_table(&self, key: &ConfigKey) -> CargoResult<OptValue<HashMap<String, CV>>> {
        match self.get_cv(key)? {
            Some(CV::Table(val, definition)) => Ok(Some(Value { val, definition })),
            Some(val) => self.expected("table", key, &val),
            None => Ok(None),
        }
    }

    get_value_typed! {get_integer, i64, Integer, "an integer"}
    get_value_typed! {get_bool, bool, Boolean, "true/false"}
    get_value_typed! {get_string_priv, String, String, "a string"}

    /// Generate an error when the given value is the wrong type.
    fn expected<T>(&self, ty: &str, key: &ConfigKey, val: &CV) -> CargoResult<T> {
        val.expected(ty, &key.to_string())
            .map_err(|e| anyhow!("invalid configuration for key `{}`\n{}", key, e))
    }

    /// Update the instance based on settings typically passed in on
    /// the command-line.
    ///
    /// This may also load the config from disk if it hasn't already been
    /// loaded.
    pub fn configure(
        &mut self,
        verbose: u32,
        quiet: bool,
        color: Option<&str>,
        frozen: bool,
        locked: bool,
        offline: bool,
        target_dir: &Option<PathBuf>,
        unstable_flags: &[String],
        cli_config: &[String],

View on GitHub (pinned to 0e07a15537)

Solutions

1. Read the two-line message: the key and the expected vs found types.
2. Correct the value in the offending source (the message's detail may name the file via the definition).
3. Check the Cargo config reference for the key's correct type and units.

Example fix

# before (.cargo/config.toml)
[build]
jobs = "8"   # string, integer expected -> invalid configuration
# after
[build]
jobs = 8

# Type-check known config keys against their expected types:
python3 - <<'EOF'
import tomllib
try: d = tomllib.load(open('.cargo/config.toml','rb'))
except FileNotFoundError: raise SystemExit(0)
schema = {'build.jobs': int, 'build.panic': str, 'term.color': str}
def get(d, p):
    for k in p.split('.'): d = d.get(k, {})
    return d
for k, t in schema.items():
    v = get(d, k)
    if v and not isinstance(v, t): raise SystemExit(f'{k}: expected {t.__name__}')
EOF

When it happens

Trigger: Any typed config read (get::<bool>, get::<i64>, get_table, etc.) where the stored value's type does not match, e.g. `[build] jobs = "abc"` (string instead of integer), or `[term] color = 1` where bool is expected.

Common situations: Misformatted config.toml; env var overriding a typed key with the wrong shape; version skew where a key's expected type changed.

Related errors

• failed to merge config value from `{}` into `{}`: expected {
• `{}` expected {}, but found a {}
• subcommand is required, add a subcommand to the command alia
• alias {} has unresolvable recursive definition: {} -> {}
• subcommand is required, but `{alias_name}` is empty

AI-assisted analysis of rust-lang/cargo@0e07a15537 (2026-08-06). Data as JSON: /data/errors/c677f1fdc3d1a7db.json. Report an issue: GitHub.