Hmbown/CodeWhale · error

--worktree-repo and --branch must be provided together

Error message

--worktree-repo and --branch must be provided together

What it means

When starting a lane with a provisioned git worktree, the CLI requires --worktree-repo and --branch as a pair: the worktree path is derived as <repo>/.codewhale/lanes/<lane-id> when --worktree-path is absent. This bail fires when exactly one of the two flags is given, because a worktree cannot be created from a repo without a branch or vice versa.

Source

Thrown at crates/cli/src/lib.rs:776

        environment,
        cwd,
    } = request;
    let kind = RuntimeBackendKind::parse(&runtime)?;
    let reg = LaneRegistry::open_default()?;
    let mut record = reg.create_pending(workflow, fleet, issue, goal, kind, worktree_ttl_secs)?;
    let worktree = match (worktree_repo, branch) {
        (Some(repo_root), Some(branch_name)) => {
            let path = worktree_path
                .unwrap_or_else(|| repo_root.join(".codewhale").join("lanes").join(&record.id));
            Some(WorktreeProvision {
                repo_root,
                branch: branch_name,
                path,
                base_ref: None,
            })
        }
        (None, None) => None,
        _ => bail!("--worktree-repo and --branch must be provided together"),
    };
    let cmd = if command.is_empty() {
        vec![
            "sh".into(),
            "-c".into(),
            format!("echo lane {} started", record.id),
        ]
    } else {
        command
    };
    let spec = LaneStartSpec {
        command: cmd,
        cwd,
        environment,
        log_proxy: (kind == RuntimeBackendKind::Tmux)
            .then(std::env::current_exe)
            .transpose()
            .context("resolve current Codewhale executable for tmux log proxy")?,

View on GitHub (pinned to 0c42157ee5)

Solutions

1. Pass both flags together: codewhale lane start --worktree-repo /src/app --branch feat/lane-1
2. Or omit both to start the lane without a worktree
3. In scripts, guard the pair: if [ -n "$REPO" ] && [ -n "$BRANCH" ]; then set -- --worktree-repo "$REPO" --branch "$BRANCH"; fi
4. Use set -u so an unset variable fails loudly instead of silently dropping one flag

Example fix

# before
codewhale lane start --runtime tmux --worktree-repo /src/app
# after
codewhale lane start --runtime tmux --worktree-repo /src/app --branch feat/lane-1

fn lane_flags_ok(worktree_repo: &Option<PathBuf>, branch: &Option<String>) -> bool {
    matches!((worktree_repo, branch), (Some(_), Some(_)) | (None, None))
}

fn worktree_flags_paired(repo: Option<&str>, branch: Option<&str>) -> bool {
    matches!((repo, branch), (Some(_), Some(_)) | (None, None))
}

When it happens

Trigger: `codewhale lane start --worktree-repo /src/app` (missing --branch) or `codewhale lane start --branch feat/x` (missing --worktree-repo); shell scripts where one variable expanded empty so only one flag survived.

Common situations: Scripted lane startup with an unset BRANCH or REPO variable; copying a partial command from docs; wrapping the flag pair conditionally (e.g. ${BRANCH:+--branch $BRANCH}) without the matching pair.

Related errors

• invalid value '{provider}' for '--provider <PROVIDER>': expe
• worktree branch must not be empty
• The Codewhale service returned an account without an ID
• `codewhale --continue` resumes the interactive TUI. Use `cod
• {flag} must be placed before `exec`. Use: codewhale {flag

AI-assisted analysis of Hmbown/CodeWhale@0c42157ee5 (2026-08-20). Data as JSON: /api/errors/2d241be054c636d2. Report an issue: GitHub.