DioxusLabs/dioxus · error

Failed to run linker

Error message

Failed to run linker

What it means

During dx's link phase the configured linker binary is spawned with the collected link args (from a response file on Windows); .expect("Failed to run linker") triggers when the process cannot start at all - binary missing, not executable, or the spawn itself errors. Linker diagnostics after a successful spawn are surfaced differently.

Source

Thrown at packages/cli/src/cli/link.rs:156

        if self.triple.environment == target_lexicon::Environment::Android {
            args.retain(|arg| !arg.ends_with(".lib"));
        }

        // Write the linker args to a file for the main process to read
        // todo: we might need to encode these as escaped shell words in case newlines are passed
        std::fs::write(&self.link_args_file, args.join("\n"))?;

        // If there's a linker specified, we use that. Otherwise, we write a dummy object file to satisfy
        // any post-processing steps that rustc does.
        match self.linker {
            Some(linker) => {
                let mut cmd = std::process::Command::new(linker);
                match cfg!(target_os = "windows") {
                    true => cmd.arg(format!("@{}", &self.link_args_file.display())),
                    false => cmd.args(args),
                };
                let res = cmd.output().expect("Failed to run linker");

                if !res.status.success() {
                    bail!(
                        "{}\n{}",
                        String::from_utf8_lossy(&res.stdout),
                        String::from_utf8_lossy(&res.stderr)
                    );
                }
                if !res.stderr.is_empty() || !res.stdout.is_empty() {
                    // Write linker warnings to file so that the main process can read them.
                    _ = std::fs::create_dir_all(self.link_err_file.parent().unwrap());
                    _ = std::fs::write(
                        self.link_err_file,
                        format!(
                            "Linker warnings: {}\n{}",
                            String::from_utf8_lossy(&res.stdout),
                            String::from_utf8_lossy(&res.stderr)
                        ),

View on GitHub (pinned to 393d190a80)

Solutions

1. Verify the linker binary exists and runs: `which <linker>` then execute it directly
2. Unset or correct custom linker env (CC, RUSTFLAGS, CARGO_TARGET_X86_64_PC_WINDOWS_MSVC_LINKER) so rustc's default linker is used
3. Install the missing toolchain package (gcc, clang, or mingw) for your host/target
4. Fall back to plain `cargo build` to confirm the linker works outside the dx wrapper

// Ensure the configured linker exists before dx serve/build
fn linker_available(linker: &str) -> bool {
    which::which(linker).is_ok()
}

When it happens

Trigger: A custom linker path/name that does not exist, CC or CARGO_TARGET_*_LINKER pointing at a removed wrapper, or permission/antivirus blocks while dx serve/dx build links.

Common situations: Toolchain updates removing clang/gcc/mingw; cross-compiling without the target linker installed; Windows paths with spaces breaking custom linker flags; antivirus blocking the spawned exe.

Related errors

• Failed to execute rustc command
• failed to execute process
• esbuild failed: {stderr}
• Failed to create args directory for rustc wrapper
• Failed to write rustc args to file

AI-assisted analysis of DioxusLabs/dioxus@393d190a80 (2026-08-16). Data as JSON: /api/errors/9a6d7808b7da8982. Report an issue: GitHub.