Overwritten [env] paths are not relative to `.cargo/config.toml`'s parent, when using config-includes

[thomasw04]

Problem

When including a config file that defines a relative path [env] variable, the including config's definition takes precedence over the included one. However, the base of that relative path seems to be incorrectly calculated.

Steps

# inc/inc.toml
[env]
MY_ENV = { value = "outer", relative = true }

# foo/.cargo/config.toml
include = ["../../inc/inc.toml"]

[env]
MY_ENV = { value = "inner", relative = true }

# foo/build.rs
fn main() {
  panic!("{}", std::env::var("MY_ENV").unwrap());
}

When running cargo +1.93.1 build, it prints foo/inner (as an absolute path to wherever foo is).
When running cargo +1.94.0 build, it prints foo/.cargo/../../inner (as an absolute path to wherever foo is).
(The behaviour of 1.95.0 is similar to 1.94.0)

Interestingly, when changing to:

# foo/.cargo/config.toml
include = ["../../inc.toml"]

cargo +1.94.0 build, prints foo/.cargo/../inner
(The behaviour of 1.95.0 is similar to 1.94.0)

Possible Solution(s)

No response

Notes

No response

Version

cargo 1.95.0 (f2d3ce0bd 2026-03-21)
release: 1.95.0
commit-hash: f2d3ce0bd7f24a49f8f72d9000448f8838c4e850
commit-date: 2026-03-21
host: x86_64-unknown-linux-gnu
libgit2: 1.9.2 (sys:0.20.4 vendored)
libcurl: 8.15.0-DEV (sys:0.4.83+curl-8.15.0 vendored ssl:OpenSSL/3.5.4)
ssl: OpenSSL 3.5.4 30 Sep 2025
os: Ubuntu 24.4.0 (noble) [64-bit]

cargo 1.94.0 (85eff7c80 2026-01-15)
release: 1.94.0
commit-hash: 85eff7c80277b57f78b11e28d14154ab12fcf643
commit-date: 2026-01-15
host: x86_64-unknown-linux-gnu
libgit2: 1.9.2 (sys:0.20.3 vendored)
libcurl: 8.17.0-DEV (sys:0.4.84+curl-8.17.0 vendored ssl:OpenSSL/3.5.4)
ssl: OpenSSL 3.5.4 30 Sep 2025
os: Ubuntu 24.4.0 (noble) [64-bit]

cargo 1.93.1 (083ac5135 2025-12-15)
release: 1.93.1
commit-hash: 083ac5135f967fd9dc906ab057a2315861c7a80d
commit-date: 2025-12-15
host: x86_64-unknown-linux-gnu
libgit2: 1.9.1 (sys:0.20.2 vendored)
libcurl: 8.15.0-DEV (sys:0.4.83+curl-8.15.0 vendored ssl:OpenSSL/3.5.4)
ssl: OpenSSL 3.5.4 30 Sep 2025
os: Ubuntu 24.4.0 (noble) [64-bit]

[ehuss]

Thanks for the report! I don't think this is a regression. The config-include feature was only added in Rust 1.94. In previous versions, the include is being ignored. Using includes will require using Rust 1.94 at a minimum.

[thomasw04]

Thanks for the reply. Yes. I forgot that config-includes were only recently stabilized.

However, even the behavior on 1.94.0/1.95.0 by itself doesn't make sense to me.

When included from inc/inc.toml: MY_ENV takes the value of inner but is relative to the parent of inc.
When included from inc.toml: MY_ENV takes the value of inner and is relative to foo.

[ehuss]

I'm not sure I quite follow. Relative paths are relative to the parent of whatever directory the config file is from.

So if you have:

# foo/.cargo/config.toml
include = ["inc/inc.toml"]

Then foo/.cargo/inc/inc.toml, the paths will be relative to the .cargo directory.

If you have:

# .cargo/config.toml
include = ["inc.toml"]

Then foo/.cargo/inc.toml, the paths will be relative to the foo directory.

---

I can perhaps see some confusion if you use .. in the path.

# .cargo/config.toml
include = ["../inc.toml"]

Then foo/inc.toml, the paths will be relative to the foo/.cargo directory because the .. segments are not normalized.

@weihanglo Do you happen to know anything about the lack of canonicalization here?

[thomasw04]

Okay. This is the directory layout in the initial example.

project-root/
├── inc/
│   └── inc.toml
└── foo/
    ├── build.rs
    ├── inner
    └── .cargo/
        └── config.toml

And config.toml includes inc.toml with

# foo/.cargo/config.toml
[env]
MY_ENV = { value = "inner", relative = true }

and

# inc/inc.toml
[env]
MY_ENV = { value = "outer", relative = true }

Now we have a variable MY_ENV defined in both config.toml and inc.toml, so config.toml takes precedence, as stated in the docs.

Now, one would expect that this variable resolves to project-root/foo/inner because config.toml took precedence.
But it actually resolves to project-root/foo/.cargo/../../inner which is project-root/inner.

And now the really odd thing is:

When the directory layout is

project-root/
├── inc.toml
└── foo/
    ├── build.rs
    ├── inner
    └── .cargo/
        └── config.toml

thus only the config-include changed from include = ["../../inc/inc.toml"] to include = ["../../inc.toml"] it suddenly resolves to project-root/foo/.cargo/../inner which is project-root/foo/inner again.

[thomasw04]

Relative paths are relative to the parent of whatever directory the config file is from.

I guess the core confusion is that it seems that when a path is defined in both inc.toml and .cargo/config.toml. The value of the variable is taken from .cargo/config.toml, but the base it is relative to is determined by the location of inc.toml.

[weihanglo]

I think the problem is not about canonicalization (it is a separate one at least). There are several layers of this bug.

1. In merge_helper, we merge all keys in a table but not the definition of the table itself:

cargo/src/cargo/util/context/config_value.rs

Lines 177 to 199 in 60960cb

	(&mut CV::Table(ref mut old, _), CV::Table(ref mut new, _)) => {
	for (key, value) in mem::take(new) {
	match old.entry(key.clone()) {
	Entry::Occupied(mut entry) => {
	let new_def = value.definition().clone();
	let entry = entry.get_mut();
	parts.push(&key);
	entry.merge_helper(value, force, parts).with_context(|| {
	format!(
	"failed to merge key `{}` between \
	{} and {}",
	key,
	entry.definition(),
	new_def,
	)
	})?;
	}
	Entry::Vacant(entry) => {
	entry.insert(value);
	}
	};
	}
	}

It is probably hard to defined the source definition of a merged struct though, perhaps people shouldn't access it to do anything meaningful.

2. When deserializing a [env] struct with Value<T>, Value<T> delegate to ValueDeserializer to deserialize the value, which only takes the struct definition into account. And that turns out to be the stale table definition:

cargo/src/cargo/util/context/de.rs

Lines 119 to 137 in 60960cb

	fn deserialize_struct<V>(
	self,
	name: &'static str,
	fields: &'static [&'static str],
	visitor: V,
	) -> Result<V::Value, Self::Error>
	where
	V: de::Visitor<'de>,
	{
	// Match on the magical struct name/field names that are passed in to
	// detect when we're deserializing `Value<T>`.
	//
	// See more comments in `value.rs` for the protocol used here.
	if name == value::NAME && fields == value::FIELDS {
	let source = ValueSource::with_deserializer(self)?;
	return visitor.visit_map(ValueDeserializer::new(source));
	}
	visitor.visit_map(ConfigMapAccess::new_struct(self, fields)?)
	}

3. Unlike file config discovery, include is loaded before the including config, hence its definition is stale and is used.

Here’s a quick fix that doesn't seem like a good long-term solution, but rather a band-aid:

diff --git a/src/cargo/util/context/config_value.rs b/src/cargo/util/context/config_value.rs
index 4af6b3c70..c3e9cdd34 100644
--- a/src/cargo/util/context/config_value.rs
+++ b/src/cargo/util/context/config_value.rs
@@ -174,7 +174,7 @@ impl ConfigValue {
                 }
                 old.sort_by(|a, b| a.definition().cmp(b.definition()));
             }
-            (&mut CV::Table(ref mut old, _), CV::Table(ref mut new, _)) => {
+            (&mut CV::Table(ref mut old, ref mut old_def), CV::Table(ref mut new, new_def)) => {
                 for (key, value) in mem::take(new) {
                     match old.entry(key.clone()) {
                         Entry::Occupied(mut entry) => {
@@ -196,6 +196,9 @@ impl ConfigValue {
                         }
                     };
                 }
+                if force || is_higher_priority {
+                    *old_def = new_def;
+                }
             }
             // Allow switching types except for tables or arrays.
             (expected @ &mut CV::List(_, _), found)

[thomasw04]

Currently, it's very unclear to me how relative paths should behave when included from a config file. The observations that I made just seemed very odd, but I couldn't actually find much in the documentation about expected behavior. For example, when looking at https://doc.rust-lang.org/cargo/reference/config.html#including-extra-configuration-files and #16284, I couldn't find any explicit mentions about it.

https://doc.rust-lang.org/cargo/reference/config.html#config-relative-paths:

Note: To maintain consistency with existing .cargo/config.toml probing behavior, it is by design that a path in a config file passed via --config is also relative to two levels up from the config file itself.

Does/should this also apply to [env] variables defined in inc.toml when not overwritten by .cargo/config.toml?

https://doc.rust-lang.org/cargo/reference/config.html#env:

Setting the relative flag evaluates the value as a config-relative path relative to the parent directory of the .cargo directory that contains the config.toml file. The value of the environment variable will be the full absolute path.

This suggests that the env variable will always be relative to the including .cargo/config.toml's parent, regardless of whether they were included from inc.toml (even when not overwritten).

In any case, the behavior seems, in some form, unintuitive. If paths in inc.toml are relative to their direct parent, that would create a situation where included files sitting in the .cargo directory behave differently from the config.toml itself. If paths in inc.toml are also relative to two levels up from themselves, this would make reasonably putting inc.toml in the root of a project impossible, as paths would need knowledge about the name of the encompassing folder.

This suggests that the env variable will always be relative to the including .cargo/config.toml's parent, regardless of whether they were included from inc.toml (even when not overwritten).

Even though not perfect, this seems to me the most reasonable. One downside that comes to my mind seems to be that it can make inc.toml, in some sense, specific to the layout of the parent folder of .cargo/config.toml that includes it, thus making sharing of inc.toml harder. However, sharing can also be achieved in some form by https://doc.rust-lang.org/cargo/reference/config.html#hierarchical-structure, where a .cargo/config.toml at the project root could just include inc.toml itself.

In any case, I think it makes sense to specify the final behavior in the docs.