# 0.9 A few common problems

> Fixes for the most common Rust setup problems: command not found, linker errors, antivirus quarantines, and more.

Source: https://learnrust.net/chapter-0/a-few-common-problems/

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](@/chapter-0/installing-rust.md) 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](@/chapter-0/installing-rust.md) 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:

```bash
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:

```bash
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.

{% callout(kind="warning", title="Warning") %}
Keep your programming projects **out of cloud-synced folders**. Desktop and Documents count, if OneDrive or iCloud is syncing them. A build writes thousands of files to `target` in seconds; sync tools lock and fiddle with files while they upload, and the two trip over each other in maddening, intermittent ways. A plain folder in your home directory (something like `~/projects`) saves you the whole genre of problem, and your cloud provider will stop lovingly backing up gigabytes of rebuildable temporary files.
{% end %}

## 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](https://users.rust-lang.org/) 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.