{"record":{"id":"9a6d7808b7da8982","repo":"DioxusLabs/dioxus","slug":"failed-to-run-linker","errorCode":null,"errorMessage":"Failed to run linker","messagePattern":"Failed to run linker","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/cli/src/cli/link.rs","lineNumber":156,"sourceCode":"\n        if self.triple.environment == target_lexicon::Environment::Android {\n            args.retain(|arg| !arg.ends_with(\".lib\"));\n        }\n\n        // Write the linker args to a file for the main process to read\n        // todo: we might need to encode these as escaped shell words in case newlines are passed\n        std::fs::write(&self.link_args_file, args.join(\"\\n\"))?;\n\n        // If there's a linker specified, we use that. Otherwise, we write a dummy object file to satisfy\n        // any post-processing steps that rustc does.\n        match self.linker {\n            Some(linker) => {\n                let mut cmd = std::process::Command::new(linker);\n                match cfg!(target_os = \"windows\") {\n                    true => cmd.arg(format!(\"@{}\", &self.link_args_file.display())),\n                    false => cmd.args(args),\n                };\n                let res = cmd.output().expect(\"Failed to run linker\");\n\n                if !res.status.success() {\n                    bail!(\n                        \"{}\\n{}\",\n                        String::from_utf8_lossy(&res.stdout),\n                        String::from_utf8_lossy(&res.stderr)\n                    );\n                }\n                if !res.stderr.is_empty() || !res.stdout.is_empty() {\n                    // Write linker warnings to file so that the main process can read them.\n                    _ = std::fs::create_dir_all(self.link_err_file.parent().unwrap());\n                    _ = std::fs::write(\n                        self.link_err_file,\n                        format!(\n                            \"Linker warnings: {}\\n{}\",\n                            String::from_utf8_lossy(&res.stdout),\n                            String::from_utf8_lossy(&res.stderr)\n                        ),","sourceCodeStart":138,"sourceCodeEnd":174,"githubUrl":"https://github.com/DioxusLabs/dioxus/blob/393d190a801ccb441d41923e232289b4f8a5c669/packages/cli/src/cli/link.rs#L138-L174","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the linker binary exists and runs: `which <linker>` then execute it directly","Unset or correct custom linker env (CC, RUSTFLAGS, CARGO_TARGET_X86_64_PC_WINDOWS_MSVC_LINKER) so rustc's default linker is used","Install the missing toolchain package (gcc, clang, or mingw) for your host/target","Fall back to plain `cargo build` to confirm the linker works outside the dx wrapper"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Ensure the configured linker exists before dx serve/build\nfn linker_available(linker: &str) -> bool {\n    which::which(linker).is_ok()\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["After toolchain changes, verify the linker binary still exists (which clang/gcc/lld)","Prefer rustc's default linker unless cross-compiling requires a custom one","Keep linker-related env (CC, CARGO_TARGET_*_LINKER) pointing at installed binaries"],"tags":["cli","linker","build","process-spawn","environment"],"backgroundTag":null,"analyzedSha":"393d190a801ccb441d41923e232289b4f8a5c669","analyzedAt":"2026-08-16T11:27:45.815Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}