{"record":{"id":"8f008714ce24c5ac","repo":"zellij-org/zellij","slug":"couldn-t-find-cargo-zigbuild","errorCode":null,"errorMessage":"couldn't find 'cargo-zigbuild'","messagePattern":"couldn't find 'cargo-zigbuild'","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"xtask/src/ci.rs","lineNumber":120,"sourceCode":"                cmd!(sh, \"{cargo} build --release\")\n                    .run()\n                    .map_err(anyhow::Error::new)\n            })\n            .context(err_context)\n    } else if cfg!(target_os = \"macos\") {\n        let target = if cfg!(target_arch = \"aarch64\") {\n            \"aarch64-unknown-linux-musl\"\n        } else {\n            \"x86_64-unknown-linux-musl\"\n        };\n        crate::cargo()\n            .and_then(|cargo| {\n                if which::which(\"cargo-zigbuild\").is_err() {\n                    eprintln!(\"!! 'cargo-zigbuild' wasn't found but is needed on macOS.\");\n                    eprintln!(\"!! Please install it with:\");\n                    eprintln!(\"!!   cargo install cargo-zigbuild\");\n                    eprintln!(\"!!   brew install zig\");\n                    return Err(anyhow::anyhow!(\"couldn't find 'cargo-zigbuild'\"));\n                }\n                cmd!(sh, \"rustup target add {target}\")\n                    .run()\n                    .map_err(anyhow::Error::new)?;\n                cmd!(sh, \"{cargo} zigbuild --release --target {target}\")\n                    .run()\n                    .map_err(anyhow::Error::new)\n            })\n            .context(err_context)\n    } else {\n        crate::cargo()\n            .and_then(|cargo| {\n                cmd!(\n                    sh,\n                    \"{cargo} build --release --target x86_64-unknown-linux-musl\"\n                )\n                .run()\n                .map_err(anyhow::Error::new)","sourceCodeStart":102,"sourceCodeEnd":138,"githubUrl":"https://github.com/zellij-org/zellij/blob/98a0837077492d53dd252ab30bc3e43e41e504f4/xtask/src/ci.rs#L102-L138","documentation":"On macOS, the E2E release build cross-compiles zellij to a static musl binary (target matching the host arch) via cargo-zigbuild. Before invoking rustup/cargo, the task checks `which cargo-zigbuild` and aborts with this error (plus install hints printed to stderr) when it is not on PATH.","triggerScenarios":"Running `cargo xtask ci e2e --build` on macOS when cargo-zigbuild is not installed, or when ~/.cargo/bin is missing from PATH so the installed binary is not found.","commonSituations":"Fresh macOS CI runners; local builds after a toolchain switch; PATH stripped in restricted shells or systemd-like environments.","solutions":["cargo install cargo-zigbuild","brew install zig (zig provides the linker backend cargo-zigbuild needs)","Verify with `which cargo-zigbuild`; if it fails, add ~/.cargo/bin to PATH and retry"],"exampleFix":"# before\ncargo xtask ci e2e --build   # !! 'cargo-zigbuild' wasn't found\n\n# after\ncargo install cargo-zigbuild\nbrew install zig\ncargo xtask ci e2e --build","handlingStrategy":"validation","validationCode":"# on macOS, gate the e2e build on the toolchain being present\nif [[ \"$(uname)\" == \"Darwin\" ]] && ! command -v cargo-zigbuild >/dev/null; then\n  echo 'installing prerequisites: cargo-zigbuild + zig'\n  cargo install cargo-zigbuild && brew install zig\nfi\ncommand -v cargo-zigbuild >/dev/null || { echo 'cargo-zigbuild required on macOS'; exit 1; }\ncargo xtask ci e2e --build","typeGuard":"fn macos_e2e_toolchain_ready() -> bool {\n    cfg!(target_os = \"macos\") && which::which(\"cargo-zigbuild\").is_ok()\n}","tryCatchPattern":"let out = Command::new(\"cargo\").args([\"xtask\", \"ci\", \"e2e\", \"--build\"]).output()?;\nlet msg = String::from_utf8_lossy(&out.stderr);\nif msg.contains(\"couldn't find 'cargo-zigbuild'\") {\n    run!(\"cargo install cargo-zigbuild\")?;\n    run!(\"brew install zig\")?;\n    rerun(out)?; // one retry after installing\n} else if !out.status.success() {\n    anyhow::bail!(\"e2e build failed: {}\", msg);\n}","preventionTips":["Provision macOS CI/development images with cargo-zigbuild and zig preinstalled","Ensure ~/.cargo/bin is on PATH in all shells that run xtask (login and non-login)","Verify with `which cargo-zigbuild` before starting long e2e build jobs"],"tags":["macos","cross-compilation","dependencies","e2e","build"],"backgroundTag":null,"analyzedSha":"98a0837077492d53dd252ab30bc3e43e41e504f4","analyzedAt":"2026-08-16T13:02:01.396Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}