cargo: More helpful error message when a stray `Cargo.toml` is present

Problem

Newcomers to Cargo occasionally end up with a Cargo.toml file that is irrelevant to the project they’re trying to run. (It is often in their home directory; perhaps they ran cargo init not understanding what it does, but that’s speculation.) When this happens, they get an error message that doesn’t really explain what is going on. An example from today:

$ cargo run
error: failed to parse manifest at '/home/user/Cargo.toml'

Caused by:
  this virtual manifest specifies a 'dependencies' section, which is not allowed

New users don’t know what a “virtual manifest” is, and are dealing with too many new concepts already to notice that /home/user/Cargo.toml isn’t their project directory, nor do they know that it doesn’t make sense to have one there. (And this message doesn’t even contain the word “workspace”!)

Proposed Solution

Two parts:

  1. When Cargo produces an error, the error is related to an invalid workspace manifest, and the purported workspace manifest path was found in a parent directory (rather than being the direct output of the locate-project algorithm), produce a message which prints the paths of both manifests rather than only the workspace manifest, with some explanation that these are two different manifests and how each relates to the situation.

  2. If the purported workspace manifest is at least two levels up from the project manifest, or is located in the user’s home directory, produce an additional help message which speculates that the workspace manifest may be extraneous and should then be either deleted or relocated to avoid nesting unrelated projects.

Notes

@rustbot label +A-diagnostics +A-workspaces +E-easy

About this issue

  • Original URL
  • State: open
  • Created 3 years ago
  • Reactions: 10
  • Comments: 16 (9 by maintainers)

Commits related to this issue

Most upvoted comments

I’d enjoy something simple, like:

error: Failed to parse a package description in this workspace's Cargo.toml file.

Caused by:
	the surrounding workspace doesn't match its Cargo.toml file. 

That moves away from the “workspace manifest” terminology while remaining helpful for more-experienced users.

If there is a way to add a help section, and we can tell if there’s some issue with the package location, I’d like to see something similar to this:

help: Try checking the placement of your Cargo.toml file and its packages. 

Also, if you do wish to continue using the manifest terminology, linking to the glossary may be neccessary: https://doc.rust-lang.org/cargo/appendix/glossary.html#manifest

In any case, if you have any advice for my input, please let me know! I’m looking to contribute more to Cargo and Rust in general. 😄

I wanted to know why Cargo just blindly accepted [packag] as a heading instead of throwing an error / warning about an unrecognised keyword.

Instead of erroring on unused keys, Cargo warns. This is helpful when we are adding new functionality to Cargo.toml that doesn’t otherwise require an MSRV bump, like adding [lints].

Furthermore, why does Cargo just assume it’s a virtual workspace just because the [package] header is missing?

A package must have at least

  • [package] (or [project])
  • [workspace]

I can see improving the error if neither is present, rather than falling through to assuming its a virtual workspace.

I stumbled across this thread trying to fix the same problem but for a different reason. For some reason, I’d accidentally deleted a character of the ‘package’ TOML header so it read ‘packag’.

All fixed now, but I wanted to know why Cargo just blindly accepted [packag] as a heading instead of throwing an error / warning about an unrecognised keyword.

Furthermore, why does Cargo just assume it’s a virtual workspace just because the [package] header is missing? Any answers are appreciated 😃

[packag]
name = "li"
version = "0.0.2"
edition = "2021"

[dependencies]
bevy = { version = "0.14.0", features = ["dynamic_linking"] }
serde = "1.0.204"

...

opt-level = 3