rust-lang/cargo · error · anyhow::Error

invalid configuration for key

Error message

invalid configuration for key `{}`
{}

What it means

Thrown by ConfigValue::expected() (called via get_integer, get_bool, get_string, etc.) when a configuration value read from config.toml, environment variables, or CLI flags does not match the expected Rust type for that configuration key. The error message names the key and describes the type mismatch.

Solutions

  1. Check the error message which names the specific key and the expected type
  2. Consult Cargo's configuration documentation for the correct type of each key
  3. Fix the value in config.toml, the environment variable, or the CLI flag to match the expected type

Example fix

# before (config.toml)
[net]
retry = "3"

# after
[net]
retry = 3
Defensive patterns

Strategy: validation

Validate before calling

// Validate config value types before loading
fn validate_config_toml(path: &Path) -> Result<(), String> {
    let content = std::fs::read_to_string(path).map_err(|e| e.to_string())?;
    let toml_val: toml::Value = toml::from_str(&content).map_err(|e| e.to_string())?;
    // Check known integer keys are integers, boolean keys are booleans, etc.
    if let Some(table) = toml_val.as_table() {
        if let Some(net) = table.get("net").and_then(|v| v.as_table()) {
            if let Some(retry) = net.get("retry") {
                if !retry.is_integer() {
                    return Err("net.retry must be an integer".into());
                }
            }
        }
    }
    Ok(())
}

Prevention

When it happens

Trigger: Providing a config value of the wrong type for a known key, e.g. setting an integer key to a string, a boolean key to an integer, or a string key to a table.

Common situations: Writing `verbose = "yes"` instead of `verbose = true` in config.toml. Setting a CARGO_* environment variable to a value that cannot be parsed as the expected type. CLI flag with wrong value type.

Related errors

AI-assisted analysis of rust-lang/cargo@98a09e7e7d (2026-08-11). Data as JSON: /api/errors/c677f1fdc3d1a7db. Report an issue: GitHub.

Appendix: source

Thrown at src/context/mod.rs:1144

    /// 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 98a09e7e7d)