xai-org/grok-build · error

git worktree add failed: {}

Error message

git worktree add failed: {}

What it means

worktree_add_no_checkout shells out to `git worktree add --no-checkout` and bails with this message when git exits non-zero, appending git's stderr. It indicates the requested worktree could not be registered or created by git — a ref conflict, an existing path, or a repo-level git error.

Source

Thrown at crates/codegen/xai-fast-worktree/src/git/worktree.rs:26

/// Create a git worktree with `--no-checkout`. Blocking.
pub(crate) fn worktree_add_no_checkout(source: &Path, dest: &str, git_ref: &str) -> Result<()> {
    let output = git_command()
        .current_dir(source)
        .args([
            "worktree",
            "add",
            "--detach",
            "--no-checkout",
            dest,
            git_ref,
        ])
        .output()
        .context("failed to run git worktree add")?;

    if !output.status.success() {
        let stderr = String::from_utf8_lossy(&output.stderr);
        anyhow::bail!("git worktree add failed: {}", stderr);
    }

    Ok(())
}

/// Which stale registrations [`remove_stale_worktree_registrations`] removes.
#[derive(Clone, Copy, Debug)]
enum StaleWorktreeMatch<'a> {
    /// Exactly the registration whose recorded worktree path is this path.
    Path(&'a Path),
    /// Every registration whose recorded worktree path is under this prefix
    /// (e.g. a tool-owned base directory, proving ownership of the entries).
    UnderPrefix(&'a Path),
}

/// Remove stale `.git/worktrees/<id>` registrations matching `match_rule`.
/// Best-effort; returns the count removed.
///

View on GitHub (pinned to bc7f02eddd)

Solutions

1. Read the embedded stderr: if it says 'already checked out', add `--detach` or use a unique branch (`git worktree add -b <new-branch> <path> <ref>`).
2. If the destination exists, remove the leftover directory or registration (`git worktree prune`, then delete the dir) before retrying.
3. Verify the target ref exists in the source repo with `git rev-parse <ref>` before creating.
4. Retry after resolving the underlying git error — worktree_add_no_checkout does not clean up partial state on its own.

Example fix

// before: reusing a branch that may already be checked out
worktree_add_no_checkout(repo, &dest, Some("main"))?;
// after: detach to allow multiple worktrees from the same ref
worktree_add_no_checkout(repo, &dest, None)?; // detached HEAD, no checkout conflict

use std::process::Command;
fn can_add_worktree(repo: &Path, dest: &Path, ref_name: Option<&str>) -> Result<(), String> {
    if dest.exists() { return Err(format!("destination {} already exists", dest.display())); }
    if let Some(r) = ref_name {
        let ok = Command::new("git").args(["rev-parse", "--verify", r]).current_dir(repo).output()
            .map(|o| o.status.success()).unwrap_or(false);
        if !ok { return Err(format!("ref {r} not found in repo")); }
    }
    Ok(())
}

match worktree_add_no_checkout(repo, &dest, ref_name) {
    Err(e) if e.to_string().contains("already checked out") => {
        // fall back to a detached worktree for the same ref
        worktree_add_no_checkout(repo, &dest, None)?;
    }
    Err(e) if e.to_string().contains("already exists") => {
        remove_leftover(&dest)?;
        worktree_add_no_checkout(repo, &dest, ref_name)?;
    }
    Err(e) => return Err(e),
    Ok(()) => {},
}

When it happens

Trigger: Creating a pooled worktree when the destination path already exists; a worktree with the same branch/ref is already checked out elsewhere (`fatal: 'ref' is already checked out`); the commit/ref doesn't exist; the main repo is bare and misconfigured, or the destination is on a read-only/failed mount.

Common situations: Re-running a create after a partial failure left the path behind; two agents creating worktrees from the same branch simultaneously; a pruned repo where the target commit was garbage-collected; NFS/Grove destination mount down mid-create.

Related errors

• git {shown} failed in {}: {}
• worktree creation task failed: {e}
• git reset --hard {} failed: {}
• git clean {} failed: {}
• git checkout {} failed: {}

AI-assisted analysis of xai-org/grok-build@bc7f02eddd (2026-08-31). Data as JSON: /api/errors/c540e2528b0afb12. Report an issue: GitHub.