Fixing 'rust-analyzer failed to load workspace' in VS Code

The Error

You open VS Code, ready to write some Rust, but instead of autocomplete and type hints you get a notification toast in the bottom right:

rust-analyzer failed to load workspace: Failed to read Cargo metadata from path '/project/Cargo.toml'

The editor goes silent — no definitions, no go-to-symbol, no hover types. Two things typically cause this. Either rust-analyzer can't find or execute cargo at all. Or it's looking for Cargo.toml in the wrong directory.

Quick Diagnosis

Before touching any settings, run this from your project root in the integrated terminal:

cargo metadata --format-version 1 --manifest-path ./Cargo.toml

Three outcomes tell you exactly where to look:

• "command not found" → it's a PATH problem
• Error about the Cargo.toml itself → syntax error or corrupted lockfile
• Works in terminal, fails in VS Code → rust-analyzer is looking in the wrong place

Step 1: Check your PATH and Toolchain

VS Code launched from a GUI (Finder, Spotlight, Start Menu) doesn't inherit your shell's PATH. So ~/.cargo/bin never gets added. This is the #1 cause on macOS and Linux.

Verify the toolchain is intact first:

rustup update
rustc --version

Works in the terminal but VS Code still fails? Try launching VS Code from the terminal directly:

code .

If that's not an option, point VS Code at the rust-analyzer binary explicitly. Open settings.json (Ctrl+Shift+P → Preferences: Open User Settings (JSON)) and add:

{
  "rust-analyzer.server.path": "~/.cargo/bin/rust-analyzer",
  "rust-analyzer.cargo.buildScripts.enable": true
}

On Windows, replace ~ with the full path: C:\\Users\\YourName\\.cargo\\bin\\rust-analyzer.exe

Step 2: Correcting the Workspace Root (Linked Projects)

Working in a mono-repo? Or did you open a parent folder that contains the crate rather than the crate root itself? That's the problem. rust-analyzer searches for Cargo.toml at the root of whatever VS Code opened — and finds nothing.

Tell the extension exactly where your manifests live. Add linkedProjects to your .vscode/settings.json:

{
  "rust-analyzer.linkedProjects": [
    "./subdir/Cargo.toml",
    "./another-crate/Cargo.toml"
  ]
}

Save the file, then open the Command Palette (Ctrl+Shift+P) and run Rust-analyzer: Restart server.

Step 3: Handling Version Mismatches

This one is subtle. The bundled rust-analyzer in VS Code can fall out of sync with your installed toolchain — especially if you're on nightly or haven't updated in a few weeks.

Run both of these:

rustup component add rust-analyzer
rustup component add rust-src

Using a specific toolchain? Pin it. Drop a rust-toolchain.toml at the project root:

[toolchain]
channel = "nightly"

This forces both cargo and rust-analyzer to use the same toolchain version — no more silent mismatches.

Step 4: The Nuclear Option (Clean and Rebuild)

cargo metadata works fine in your terminal but VS Code still shows the error? Something is corrupted. Close VS Code entirely, then run:

cargo clean
rm -rf ./.cargo-lock  # if it exists
rm -rf ~/.cache/rust-analyzer  # Linux
# macOS: rm -rf ~/Library/Caches/rust-analyzer

Reopen VS Code. Watch the status bar — you'll see an "Indexing" progress indicator. On a medium project with ~50 crates, this takes about 30–60 seconds. Let it finish completely before testing anything.

Verification

How do you know it's actually fixed?

• The status bar shows rust-analyzer ✓ or "Indexing" — not a red error icon
• Hover over any variable — a tooltip with the inferred type pops up immediately
• Open the Output panel, select Rust Analyzer Language Server from the dropdown. You want to see "Finished cargo metadata loading", not error stack traces

Pro Tips

• Workspace Cargo.toml: In a multi-crate workspace, the root Cargo.toml must have a [workspace] section that lists every member. Missing entries cause this exact error for unlisted crates.
• noexec mounts on Linux: If your project lives on a mount with the noexec flag, cargo can't run build scripts. Check with mount | grep noexec and remount without the flag if needed.
• Extension conflicts: Don't run the old "Rust" extension alongside "rust-analyzer" — they fight over the language server and both lose. Disable or uninstall the old one.