rust-lang/rust-analyzer · error

cargo check failed to start: {err}

Error message

cargo check failed to start: {err}

What it means

rust-analyzer's flycheck (cargo check) integration records a 'cargo check failed to start' message in last_flycheck_error when the cargo process could not be spawned or exited with a startup failure. The message surfaces in the IDE as an error notification/progress end. It indicates the configured cargo check command never actually ran.

Source

Thrown at crates/rust-analyzer/src/main_loop.rs:1294

                let (state, message) = match progress {
                    flycheck::Progress::DidStart { user_facing_command } => {
                        self.flycheck_formatted_commands[id] = format_with_id(user_facing_command);
                        (Progress::Begin, None)
                    }
                    flycheck::Progress::DidCheckCrate(target) => (Progress::Report, Some(target)),
                    flycheck::Progress::DidCancel => {
                        self.last_flycheck_error = None;
                        *cargo_finished = true;
                        (Progress::End, None)
                    }
                    flycheck::Progress::DidFailToRestart(err) => {
                        self.last_flycheck_error =
                            Some(format!("cargo check failed to start: {err}"));
                        return;
                    }
                    flycheck::Progress::DidFinish(result) => {
                        self.last_flycheck_error =
                            result.err().map(|err| format!("cargo check failed to start: {err}"));
                        *cargo_finished = true;
                        (Progress::End, None)
                    }
                };

                // Clone because we &mut self for report_progress
                let title = self.flycheck_formatted_commands[id].clone();
                self.report_progress(
                    &title,
                    state,
                    message,
                    None,
                    Some(format!("rust-analyzer/flycheck/{id}")),
                );
            }
        }
    }

View on GitHub (pinned to e8f7e90aa3)

Solutions

1. Verify `cargo check` runs in a terminal from the workspace root; fix PATH or install rustup/cargo if not.
2. If check.overrideCommand is set, correct it or remove it to use the default `cargo check --workspace ...`.
3. Check rust.analyzer.linkedProjects / workspace layout — a bad root can make cargo fail immediately.
4. Reinstall/repair the toolchain (rustup update / rustup component add) if the shim or toolchain is broken.
5. Check the rust-analyzer output channel for the underlying `err` detail.

Example fix

// before (settings.json)
"rust-analyzer.check.overrideCommand": ["cargo", "clippy-x", "--workspace"]
// after
"rust-analyzer.check.overrideCommand": ["cargo", "clippy", "--workspace", "--message-format=json"]

# Before launching rust-analyzer, verify flycheck can run:
cargo check --workspace --message-format=json > /dev/null && echo OK || echo FIX_ENV

// Client side (VS Code): listen for window/showMessage type=Error
client.onNotification(lsp.ShowMessageNotification.type, (p) => {
  if (p.message.startsWith('cargo check failed to start')) {
    // surface remediation: check PATH / check.overrideCommand
  }
});

When it happens

Trigger: flycheck::Progress::DidFailToStart with an err — e.g. the cargo binary isn't found, the configured overrideCommand is invalid/unavailable, or the spawn failed — and DidFinish returning an Err result with the same startup-failure semantics.

Common situations: rust-analyzer installed in an environment without cargo in PATH; a custom `rust-analyzer.check.overrideCommand` pointing to a nonexistent binary; running the IDE inside a container/WSL where the toolchain isn't installed; workspace where cargo can't start due to a broken toolchain (rustup shim issues).

Related errors

• Cannot rename builtin type
• {message}
• Project discovery failed: {error}
• We explicitly do not provide canonicalization API, as that i
• bad kind {other}

AI-assisted analysis of rust-lang/rust-analyzer@e8f7e90aa3 (2026-09-03). Data as JSON: /api/errors/6aa73f5c71ac0bc8. Report an issue: GitHub.