Sửa lỗi 'rust-analyzer failed to load workspace' trong VS Code

Lỗi Gặp Phải

Bạn mở VS Code, sẵn sàng viết Rust, nhưng thay vì autocomplete và gợi ý kiểu dữ liệu, bạn lại thấy một thông báo pop-up ở góc dưới bên phải:

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

Editor trở nên im lặng — không có định nghĩa, không có go-to-symbol, không có hover types. Thường có hai nguyên nhân gây ra điều này: hoặc rust-analyzer không tìm thấy hoặc không thể chạy được cargo, hoặc nó đang tìm Cargo.toml ở sai thư mục.

Chẩn Đoán Nhanh

Trước khi chỉnh bất kỳ cài đặt nào, hãy chạy lệnh này từ thư mục gốc của project trong terminal tích hợp:

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

Ba kết quả sẽ cho bạn biết chính xác cần xem xét ở đâu:

• "command not found" → đây là vấn đề với PATH
• Lỗi liên quan đến chính file Cargo.toml → lỗi cú pháp hoặc lockfile bị hỏng
• Chạy được trong terminal nhưng VS Code vẫn lỗi → rust-analyzer đang tìm sai vị trí

Bước 1: Kiểm Tra PATH và Toolchain

VS Code khởi động từ giao diện đồ họa (Finder, Spotlight, Start Menu) sẽ không kế thừa PATH của shell. Do đó ~/.cargo/bin không bao giờ được thêm vào. Đây là nguyên nhân hàng đầu trên macOS và Linux.

Trước tiên hãy kiểm tra xem toolchain có nguyên vẹn không:

rustup update
rustc --version

Chạy được trong terminal nhưng VS Code vẫn lỗi? Thử khởi động VS Code trực tiếp từ terminal:

code .

Nếu không thể làm vậy, hãy chỉ định đường dẫn tới binary rust-analyzer cho VS Code. Mở settings.json (Ctrl+Shift+P → Preferences: Open User Settings (JSON)) và thêm vào:

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

Trên Windows, thay ~ bằng đường dẫn đầy đủ: C:\\Users\\YourName\\.cargo\\bin\\rust-analyzer.exe

Bước 2: Sửa Thư Mục Gốc Workspace (Linked Projects)

Bạn đang làm việc với mono-repo? Hoặc bạn đã mở thư mục cha chứa crate thay vì mở chính thư mục gốc của crate? Đó chính là vấn đề. rust-analyzer tìm kiếm Cargo.toml tại thư mục gốc mà VS Code đang mở — và không tìm thấy gì.

Hãy chỉ định chính xác vị trí các file manifest cho extension. Thêm linkedProjects vào file .vscode/settings.json của bạn:

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

Lưu file, sau đó mở Command Palette (Ctrl+Shift+P) và chạy Rust-analyzer: Restart server.

Bước 3: Xử Lý Xung Đột Phiên Bản

Đây là trường hợp khá tinh vi. Phiên bản rust-analyzer được tích hợp sẵn trong VS Code có thể bị lệch so với toolchain bạn đang cài — đặc biệt nếu bạn dùng nightly hoặc không cập nhật trong vài tuần gần đây.

Chạy cả hai lệnh này:

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

Đang dùng một toolchain cụ thể? Hãy ghim phiên bản lại. Tạo file rust-toolchain.toml tại thư mục gốc của project:

[toolchain]
channel = "nightly"

Cách này buộc cả cargo lẫn rust-analyzer phải dùng cùng một phiên bản toolchain — không còn xung đột phiên bản âm thầm nữa.

Bước 4: Phương Án Triệt Để (Xóa Sạch và Build Lại)

cargo metadata chạy tốt trong terminal nhưng VS Code vẫn hiển thị lỗi? Có gì đó đã bị hỏng. Đóng hoàn toàn VS Code, sau đó chạy:

cargo clean
rm -rf ./.cargo-lock  # nếu file này tồn tại
rm -rf ~/.cache/rust-analyzer  # Linux
# macOS: rm -rf ~/Library/Caches/rust-analyzer

Mở lại VS Code. Quan sát thanh trạng thái — bạn sẽ thấy chỉ số tiến trình "Indexing". Với project cỡ vừa khoảng ~50 crate, quá trình này mất khoảng 30–60 giây. Hãy để nó hoàn tất hoàn toàn trước khi kiểm tra bất cứ điều gì.

Kiểm Tra Kết Quả

Làm sao biết lỗi đã được sửa thực sự?

• Thanh trạng thái hiển thị rust-analyzer ✓ hoặc "Indexing" — không còn biểu tượng lỗi màu đỏ
• Di chuột qua bất kỳ biến nào — tooltip hiển thị kiểu dữ liệu được suy luận xuất hiện ngay lập tức
• Mở bảng Output, chọn Rust Analyzer Language Server từ danh sách thả xuống. Bạn muốn thấy "Finished cargo metadata loading", chứ không phải các stack trace lỗi

Mẹo Hay

• Workspace Cargo.toml: Trong một workspace nhiều crate, file Cargo.toml gốc phải có phần [workspace] liệt kê tất cả các thành viên. Thiếu mục nào sẽ gây ra chính xác lỗi này cho các crate không được liệt kê.
• noexec mounts trên Linux: Nếu project của bạn nằm trên một mount có cờ noexec, cargo sẽ không thể chạy build scripts. Kiểm tra bằng lệnh mount | grep noexec và remount lại mà không có cờ đó nếu cần.
• Xung đột extension: Đừng chạy extension "Rust" cũ cùng lúc với "rust-analyzer" — chúng sẽ tranh giành language server và cả hai đều không hoạt động được. Hãy tắt hoặc gỡ cài đặt extension cũ đi.