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

Missing 'worktree_path' parameter for worktree add

Error message

Missing 'worktree_path' parameter for worktree add

What it means

Inside git_worktree, the "add" branch requires a 'worktree_path' string in the args; if it is missing or not a string, the tool bails with 'Missing 'worktree_path' parameter for worktree add'. The path is subsequently sanitized and passed through ensure_worktree_add_target_allowed, which constrains where a new worktree may be created — but the bail here happens first, purely on argument shape. It fires only when subcommand == "add".

Source

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

        match subcommand {
            "list" => {
                let output = self
                    .run_git_command(&["worktree", "list", "--porcelain"], working_dir)
                    .await?;
                let parsed = self.parse_worktree_list(&output);
                Ok(ToolResult {
                    success: true,
                    output: serde_json::to_string_pretty(&parsed)
                        .unwrap_or_default()
                        .into(),
                    error: None,
                })
            }
            "add" => {
                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 add"),
                };
                self.sanitize_git_args(worktree_path)?;
                let worktree_path = self.ensure_worktree_add_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")
                })?;

                let branch = args
                    .get("branch")
                    .and_then(|v| v.as_str())
                    .unwrap_or_default();
                // git worktree add <path> [<branch>]

View on GitHub (pinned to 88bb9c8533)

Solutions

1. Include an explicit absolute or repo-relative path string: {"subcommand": "add", "worktree_path": "/tmp/zc-feature"}.
2. Verify the key name is exactly 'worktree_path' (snake_case).
3. Validate that the path variable is set before constructing args; fail fast in the caller with your own clearer message.
4. Check that the target directory location is allowed by the tool's worktree-add target policy, since that check runs right after this one.

Example fix

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

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

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

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

match tool_result {
    Err(e) if e.to_string().contains("for worktree add") => {
        // the path never made it into args; rebuild args with an explicit path
    }
    other => other,
}

When it happens

Trigger: Calling the worktree tool with {"subcommand": "add"} and no 'worktree_path' key; passing a non-string value like {"worktree_path": 42} or null; misspelling the key as "path" or "worktree". Passing a blank string does NOT hit this error (it is a string) and instead flows into sanitization/target checks.

Common situations: A caller assumes the tool derives the worktree path from the branch name; an agent emits only the branch argument; a script builds args conditionally and the path variable was unset; key-name drift between the tool schema and the caller after a version change.

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 remove
• 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/5ac3e5784ed03dba. Report an issue: GitHub.