Error messages about modules are confusing to beginners

[jmikkola]

When a beginner [0] first tries to use modules, they are likely to do it wrong. The error message printed is misleading because it only mentions extern crate foo and never mentions

Example

Consider the following project:

src/main.rs:

use foo::say_hello;

fn main() {
    say_hello();
}

src/foo.rs:

pub fn say_hello() {
    println!("Hello, world!");
}

Running cargo run results in the following error message:

   Compiling confusion v0.1.0 (file:///home/jeremy/tmp/confusion)
error[E0432]: unresolved import `foo`
 --> src/main.rs:1:5
  |
1 | use foo::say_hello;
  |     ^^^ Maybe a missing `extern crate foo;`?

error: aborting due to previous error

For more information about this error, try `rustc --explain E0432`.
error: Could not compile `confusion`.

To learn more, run the command again with --verbose.

Naturally, one might try adding extern crate foo; to the top of main.rs. This changes the error message to:

   Compiling confusion v0.1.0 (file:///home/jeremy/tmp/confusion)
error[E0463]: can't find crate for `foo`
 --> src/main.rs:1:1
  |
1 | extern crate foo;
  | ^^^^^^^^^^^^^^^^^ can't find crate

error: aborting due to previous error

For more information about this error, try `rustc --explain E0463`.
error: Could not compile `confusion`.

To learn more, run the command again with --verbose.

If a user reads the output of rustc --explain E0432, they might instead try changing main.rs to start with use self::foo::say_hello;, though this does not change the error message.

Another common thing to try is adding mod foo; or pub mod foo; to the top of foo.rs. It is very unlikely that a user will stumble upon an actual solution (such as adding mod foo; to the top of main.rs).

Suggestion

The error message should also mention how to refer to local modules, not just external crates.

If there is a file that matches the module name the user is trying to import, it would be especially helpful if the error message discussed how to correctly use that module from main.rs.

Meta

$ rustc --version
rustc 1.26.0 (a77568041 2018-05-07)

[0] or myself, after having not touched Rust in over a year

[shingtaklam1324]

Perhaps when rustc or (cargo actually) finds use foo::say_hello; and the module/crate foo is not defined, search for src/foo.rs and src/foo/mod.rs, and if it finds it, use the (new?) error message referring to modules, and if there isn't one, use the current error message.

I'm not sure how feasible this will be to implement.

Given one of the Rust 2018 goals being removing extern crate, this issue would be affected by that as well, so I'm not sure on the priority of fixing this at the moment.

[sitaktif]

I just stumbled upon a very similar issue:

main.rs:

mod mymod;

fn main() {
    say_hello();
}

mymod.rs:

use crate::util;

util::foo()

Getting the following error message:

1 | use crate::util::foo;
  |            ^^^^ maybe a missing `extern crate util;`?

...when actually I was missing a pub(crate) mod util; in main.rs.

I find this one particularly hard to debug because although we're trying to use util.rs from mymod.rs, the missing line change is in neither file.

[gibfahn]

The error message seems particularly confusing as extern crate util should never be needed in 2018 edition crates, so this error will I think be always incorrect.

[steveklabnik]

Triage: i tried to recreate this bug, in both the 2015 and 2018 editions, and it compiles in each one https://play.rust-lang.org/?version=stable&mode=debug&edition=2015&gist=768534f142eaea262b568767f02adacb

[steveklabnik]

Oh. Immediately after posting that, I realized my error: the original example did not have a mod declaration. That means the actual equivalent is

use foo::say_hello;

fn main() {
    say_hello();
}

and the error is now

error[E0432]: unresolved import `foo`
 --> src/main.rs:1:5
  |
1 | use foo::say_hello;
  |     ^^^ use of undeclared crate or module `foo`

error: aborting due to previous error

with no suggestions, in the 2018 edition, but

error[E0432]: unresolved import `foo`
 --> src/main.rs:1:5
  |
1 | use foo::say_hello;
  |     ^^^ maybe a missing crate `foo`?

in the 2015 edition.

[hkBst]

This seems to have been fixed (tested both 2015 and 2024 editions):

src/main.rs:

fn main() {
    r#mod::f()
}

*src/mod.rs *:

fn f() {}

$ cargo run
   Compiling missing-mod-statement v0.1.0 (/home/gh-hkBst/crates/missing-mod-statement)
error[E0433]: failed to resolve: use of unresolved module or unlinked crate `r#mod`
 --> src/main.rs:2:5
  |
2 |     r#mod::f()
  |     ^^^^^ use of unresolved module or unlinked crate `r#mod`
  |
help: to make use of source file src/mod.rs, use `mod r#mod` in this file to declare the module
  |
1 + mod r#mod;
  |

For more information about this error, try `rustc --explain E0433`.