cross-rs/cross · warning

found unused key(s) in Cross configuration

Error message

found unused key(s) in Cross configuration{}:
 > {}

What it means

cross parses the `Cross.toml` config with serde and tracks keys that serde never consumed via `serde_ignored`. When any key in the configuration is not recognized (e.g. a typo or a key from an older cross version), it emits this warning listing the unused keys and where the config came from.

Solutions

1. Open Cross.toml and compare each listed unused key against the documented cross configuration schema; fix typos or remove stale keys.
2. Move the key to the correct nesting level if it is a valid option placed in the wrong table.
3. Check the installed cross version's documentation; keys valid in older versions may have been renamed or removed.
4. If the key is intentionally informational (e.g. custom metadata), move it out of Cross.toml or ignore the warning.

Example fix

# before (Cross.toml)
[build.env]
passthrough = ["RUSTFLAGS"]

# after
[build.env]
passthrough = ["RUSTFLAGS"]
# key must be valid; e.g. typo'd 'passthru' or unknown 'mycustomkey' removed

// Pre-validate Cross.toml keys against known top-level tables
let known = ["build", "target", "env", "ci"];
let cfg: toml::Value = toml::from_str(&toml_text)?;
for (k, _) in cfg.as_table().unwrap() {
    if !known.contains(&k.as_str()) {
        eprintln!("unknown Cross.toml key: {}", k);
    }
}

When it happens

Trigger: Deserializing a Cross.toml (or config from another source) in parse_from_deserializer when one or more top-level or nested keys do not match any field of the cross `Configuration` struct, such as misspelled table names like `[build.env]` instead of `[build.env.volumes]` or obsolete keys.

Common situations: Typos in Cross.toml keys; following outdated blog posts referencing keys removed in newer cross versions; placing keys at the wrong nesting level (serde matches exact paths); copying config snippets for a different tool.

Related errors

• failed to serialize CrossToml as object
• unable to find provided nix-store directory
• unsupported rust target for file
• invalid linux version, got
• a target named " " is mentioned in the Cross configuration…

AI-assisted analysis of cross-rs/cross@8c1a8aa4b6 (2026-09-13). Data as JSON: /api/errors/a10f024f4e1ae6d6. Report an issue: GitHub.

Appendix: source

Thrown at src/cross_toml.rs:199

    }

    /// Parses the [`CrossToml`] from a [`Deserializer`]
    pub fn parse_from_deserializer<'de, D>(
        deserializer: D,
        source: Option<&str>,
        msg_info: &mut MessageInfo,
    ) -> Result<(Self, BTreeSet<String>)>
    where
        D: Deserializer<'de>,
        D::Error: Send + Sync + 'static,
    {
        let mut unused = BTreeSet::new();
        let cfg = serde_ignored::deserialize(deserializer, |path| {
            unused.insert(path.to_string());
        })?;

        if !unused.is_empty() {
            msg_info.warn(format_args!(
                "found unused key(s) in Cross configuration{}:\n > {}",
                source.map(|s| format!(" at {s}")).unwrap_or_default(),
                unused.clone().into_iter().collect::<Vec<_>>().join(", ")
            ))?;
        }

        Ok((cfg, unused))
    }

    /// Merges another [`CrossToml`] into `self` and returns a new merged one
    pub fn merge(self, other: CrossToml) -> Result<CrossToml> {
        type ValueMap = serde_json::Map<String, serde_json::Value>;

        fn to_map<S: Serialize>(s: S) -> Result<ValueMap> {
            if let Some(obj) = serde_json::to_value(s)
                .wrap_err("could not convert CrossToml to serde_json::Value")?
                .as_object()
            {

View on GitHub (pinned to 8c1a8aa4b6)