{"record":{"id":"31333533aeda8b23","repo":"zeroclaw-labs/zeroclaw","slug":"archive-does-not-contain-a-target-name-binary","errorCode":null,"errorMessage":"archive does not contain a '{target_name}' binary","messagePattern":"archive does not contain a '(.+?)' binary","errorType":"validation","errorClass":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"src/commands/update.rs","lineNumber":671,"sourceCode":"/// Find the freshly unpacked main binary in `staging`.\n///\n/// Walks the staged tree looking for a `zeroclaw` (or `zeroclaw.exe`) file. The\n/// release archive is flat — the binary sits at the staging root — but we walk\n/// in case a future archive layout introduces a wrapper directory (e.g.\n/// `zeroclaw-v0.9/zeroclaw.exe`, which Windows zip tooling sometimes produces).\nfn locate_main_binary(staging: &Path) -> Result<PathBuf> {\n    let target_name = main_binary_name();\n    for entry in walk_files(staging) {\n        if entry\n            .file_name()\n            .and_then(|n| n.to_str())\n            .map(|n| n == target_name)\n            .unwrap_or(false)\n        {\n            return Ok(entry);\n        }\n    }\n    bail!(\"archive does not contain a '{target_name}' binary\")\n}\n\n/// Collect all **regular file** paths under `root`, skipping directories and\n/// symlinks. Used by `locate_main_binary` so it sees the same view of the\n/// staged tree as `install_companion_artifacts`.\nfn walk_files(root: &Path) -> Vec<PathBuf> {\n    let mut out = Vec::new();\n    let mut stack = vec![root.to_path_buf()];\n    while let Some(dir) = stack.pop() {\n        let Ok(entries) = std::fs::read_dir(&dir) else {\n            continue;\n        };\n        for entry in entries.flatten() {\n            // file_type() does *not* follow symlinks, so a symlink shows up as\n            // is_symlink() — we drop it rather than dereferencing it.\n            let Ok(ft) = entry.file_type() else { continue };\n            let path = entry.path();\n            if ft.is_dir() {","sourceCodeStart":653,"sourceCodeEnd":689,"githubUrl":"https://github.com/zeroclaw-labs/zeroclaw/blob/88bb9c8533fc57ed7a03e36ca7c9ed2bf8336dcc/src/commands/update.rs#L653-L689","documentation":"After downloading and checksum-verifying the release .tar.gz, the updater unpacks it into a staging directory and locate_main_binary (via walk_files) scans only regular files, skipping directories and symlinks, for the main binary named 'zeroclaw' (zeroclaw.exe on Windows). This error means no such regular file exists anywhere in the staged tree, so there is nothing to install.","triggerScenarios":"`zeroclaw update` completes download and unpack, but the archive contains no regular file whose name is 'zeroclaw': the binary is missing, shipped only as a symlink (walk_files skips symlinks), nested under a differently-named path in a changed release layout, or the wrong asset (e.g. a source tarball) was downloaded.","commonSituations":"Mispackaged release where the packaging script renamed or omitted the top-level binary; release layout change (versioned top-level directory) that the running zeroclaw version does not understand; asset-name to content mismatch on the release.","solutions":["Download the same release asset manually and list its contents: `tar -tzf zeroclaw-*.tar.gz | head -30` to confirm whether a top-level 'zeroclaw' regular file exists.","If the archive is wrong, report the mispackaged release and update to the nearest fixed version.","If the release layout changed, update zeroclaw to the version that supports the new layout (or install that release manually from the release page).","As a workaround, install the binary from the archive by hand into the current install directory."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"#!/usr/bin/env bash\n# pre-flight before `zeroclaw update`: archive must contain the main binary\nurl=\"https://github.com/zeroclaw/zeroclaw/releases/download/vX/zeroclaw-x86_64-linux.tar.gz\"\nif ! curl -fsSL \"$url\" | tar -tz | grep -qx 'zeroclaw'; then\n  echo \"release archive lacks the zeroclaw binary\" >&2; exit 1\nfi","typeGuard":null,"tryCatchPattern":"match run_update().await {\n    Err(e) if e.to_string().contains(\"does not contain a '\") => {\n        // mispackaged archive: stop, report the release, do not retry\n    }\n    other => other,\n}","preventionTips":["In release CI, assert `tar -tzf <asset>` contains a top-level regular file named zeroclaw (not a symlink) before publishing.","Keep the release archive layout stable across versions; treat layout changes as breaking for old updaters.","Test the self-updater against the staged release artifacts in CI."],"tags":["update","release-artifact","tarball","packaging","binary"],"backgroundTag":"archive-missing-expected-file","analyzedSha":"88bb9c8533fc57ed7a03e36ca7c9ed2bf8336dcc","analyzedAt":"2026-08-23T01:07:41.857Z","schemaVersion":2},"datasetVersion":"2026-08-23T08:06:27.607Z"}