zeroclaw-labs/zeroclaw · error · anyhow::Error

Missing 'worktree_path' parameter for worktree remove

Error message

Missing 'worktree_path' parameter for worktree remove

What it means

Inside git_worktree, the "remove" branch requires a 'worktree_path' string in the args; if missing or not a string, the tool bails with 'Missing 'worktree_path' parameter for worktree remove'. After this shape check, the path is sanitized and passed through ensure_worktree_remove_target_allowed, which restricts which worktrees may be removed — a safety gate against deleting directories outside the managed set. The bail here is purely about argument presence/type and fires only when subcommand == "remove".

Source

Thrown at crates/zeroclaw-tools/src/git_operations.rs:817

                    .unwrap_or_default();
                // git worktree add <path> [<branch>]
                let mut git_args = vec!["worktree", "add", worktree_path];
                if !branch.is_empty() {
                    self.sanitize_git_args(branch)?;
                    git_args.push(branch);
                }

                self.run_git_command(&git_args, working_dir).await?;
                Ok(ToolResult {
                    success: true,
                    output: format!("Worktree added at: {worktree_path}").into(),
                    error: None,
                })
            }
            "remove" => {
                let worktree_path = match args.get("worktree_path").and_then(|v| v.as_str()) {
                    Some(p) => p,
                    None => anyhow::bail!("Missing 'worktree_path' parameter for worktree remove"),
                };
                self.sanitize_git_args(worktree_path)?;
                let worktree_path = self.ensure_worktree_remove_target_allowed(worktree_path)?;
                let worktree_path = worktree_path.to_str().ok_or_else(|| {
                    ::zeroclaw_log::record!(
                        WARN,
                        ::zeroclaw_log::Event::new(module_path!(), ::zeroclaw_log::Action::Reject)
                            .with_outcome(::zeroclaw_log::EventOutcome::Failure),
                        "git_operations: worktree path not valid UTF-8"
                    );
                    anyhow::Error::msg("Worktree path must be valid UTF-8 for git execution")
                })?;

                self.run_git_command(&["worktree", "remove", worktree_path], working_dir)
                    .await?;
                Ok(ToolResult {
                    success: true,
                    output: format!("Worktree removed: {worktree_path}").into(),

View on GitHub (pinned to 88bb9c8533)

Solutions

1. Include the exact path string: {"subcommand": "remove", "worktree_path": "/tmp/zc-feature"}.
2. Derive the path from the immediately preceding "list" subcommand's porcelain output rather than reconstructing it by convention.
3. Confirm the key is 'worktree_path' and the value is a JSON string, not null.
4. Expect the follow-up policy check: the target must be an allowed worktree location, so remove paths you created through this tool.

Example fix

// before
let args = serde_json::json!({ "subcommand": "remove" });
// tool bails: Missing 'worktree_path' parameter for worktree remove

// after
let args = serde_json::json!({ "subcommand": "remove", "worktree_path": "/tmp/zc-feature" });

fn build_worktree_remove(path: &str) -> Option<serde_json::Value> {
    (!path.is_empty()).then(|| serde_json::json!({ "subcommand": "remove", "worktree_path": path }))
}

fn is_valid_worktree_remove_args(args: &serde_json::Value) -> bool {
    args.get("subcommand").and_then(|v| v.as_str()) == Some("remove")
        && args.get("worktree_path").and_then(|v| v.as_str()).is_some()
}

match tool_result {
    Err(e) if e.to_string().contains("for worktree remove") => {
        // re-run "list", parse the porcelain path, and retry with it
    }
    other => other,
}

When it happens

Trigger: Calling {"subcommand": "remove"} with no 'worktree_path'; passing {"worktree_path": null} or a number; using a different key such as "target" or "path". Running "list" first and forgetting to copy the path from its output into the remove call.

Common situations: Cleanup scripts iterate a hardcoded branch list but forget the path mapping; an agent removes a worktree it created earlier but loses the path between turns; the path came from parsing `worktree list --porcelain` output and the extraction returned None, serializing to a missing key.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• Missing 'subcommand' parameter. Use: list, add, remove, prun
• Missing 'worktree_path' parameter for worktree add
• Unknown worktree subcommand: {subcommand}. Use: list, add, r
• Path not allowed: contains null byte
• Path not allowed: parent-directory traversal is not allowed

AI-assisted analysis of zeroclaw-labs/zeroclaw@88bb9c8533 (2026-08-23). Data as JSON: /api/errors/3bb856f67a656625. Report an issue: GitHub.