0.9A few common problems

Last updated June 11, 2026

Setup problems have a special cruelty: they arrive before you know enough to diagnose anything, and they block absolutely everything. So this lesson is a reference for the handful of problems that account for most beginner setup grief. Skim it now, and remember it exists. If something here bites you next week, the fix is waiting.

(If your problem isn't on this page, the last section covers how to hunt down answers for anything.)

Q: I type cargo and the terminal says it doesn't exist

On Windows the message looks like 'cargo' is not recognized as an internal or external command; on macOS and Linux, command not found: cargo.

If you just installed Rust: your terminal is the problem, not Rust. A terminal reads the system's PATH (the list of folders it searches for commands) once, when it opens. The installer updated the PATH, but already-open terminals don't get the memo. Close the terminal entirely (every tab and window) and open a fresh one.

If a fresh terminal still doesn't know cargo, check whether Rust actually finished installing: the tools live in .cargo/bin inside your home folder. If that folder is empty or missing, re-run the installer from lesson 0.6 and read its final messages carefully; they say exactly what it did and didn't do.

Q: On Windows: error: linker `link.exe` not found

This is the classic Windows stumble, and it means the Microsoft C++ Build Tools prerequisite from lesson 0.6 isn't installed (or was installed without the right pieces). Rust compiles your code, but the final stitching-together step uses Microsoft's linker, which ships with the Build Tools: no Build Tools, no executables.

Go back to the prerequisite step in 0.6: install the Build Tools with the "Desktop development with C++" workload selected, restart your machine for good measure, and try again.

Q: On macOS: the build fails mentioning cc, linker, or xcrun

Same disease, Apple strain: the linker on macOS comes from Apple's Command Line Tools. Run:

xcode-select --install

accept the dialog, give it a few minutes, and rebuild.

Q: My program compiled, then vanished, or won't run because of "a virus"

Your compiler produces brand-new executable files that no one has ever seen before, with no signature and no reputation. To certain antivirus products, that's exactly what malware looks like, and they will occasionally quarantine your two-line hello-world as a precaution. (Your antivirus has never written a program, but it has opinions about yours.)

If a program you just built disappears or refuses to run with a security complaint: check the antivirus's quarantine history to confirm, restore the file, and add your projects folder to the antivirus's exclusion list so it stops happening. On Windows, this applies to Microsoft Defender too; exclusions live under Virus & threat protection settings.

Q: Everything worked yesterday, and today the build fails with something incomprehensible

First, try the time-honored ritual:

cargo clean
cargo build

cargo clean deletes the target folder (the workshop of intermediate files Cargo keeps between builds) and forces the next build to start from scratch. A half-written or stale file in target, left by a crash, a forced shutdown, or an overeager cleanup utility, can produce truly baffling errors, and cargo clean cures that entire category. It's safe: nothing in target is your work, and Cargo rebuilds all of it.

Q: One mistake produced a screen full of errors. Do I have to fix them all?

Read the first error and fix that one; then recompile and see what remains. A single early mistake routinely confuses the compiler about everything after it, producing a cascade of secondary complaints that evaporate when the real one is fixed. Scrolling up beats despairing. (Reading Rust's errors properly is a skill we'll build in lesson 1.7.)

Q: My problem isn't on this page

Then here's the general algorithm, in escalation order:

1. Search the exact message. Copy the error text into a search engine, in quotes, minus parts specific to you (your file paths, your project name). Setup problems are almost never original; someone has posted yours, and someone else has answered it.

2. Ask an AI assistant — to explain, not to fix. Paste the full error and ask what it means. While you're learning, "explain this to me" builds the skill; "make this go away" quietly outsources it, and the skill is the thing you're here for.

3. Ask humans. The Rust users forum is friendly to beginners, and Stack Overflow works if you show your homework. Either way, include the smallest program that reproduces the problem, the exact command you ran, and the complete error. Questions with those three answer themselves surprisingly often, and get answered fast when they don't.

And a permanent truth, hereby enshrined: the bug that survives an hour of staring rarely survives a night of sleep.