eyaltoledano/claude-task-master · error

branchName is required for isBranchCheckedOut

Error message

branchName is required for isBranchCheckedOut

What it means

isBranchCheckedOut() requires a branch name to search for among worktrees; if branchName is missing/empty it throws before querying worktrees. This prevents an ambiguous lookup that would never match any worktree.

Source

Thrown at packages/tm-core/src/common/utils/git-utils.ts:415

		return worktrees;
	} catch (error) {
		return [];
	}
}

/**
 * Check if a branch is checked out in any worktree
 * Returns the worktree path if found, null otherwise
 */
export async function isBranchCheckedOut(
	projectRoot: string,
	branchName: string
): Promise<string | null> {
	if (!projectRoot) {
		throw new Error('projectRoot is required for isBranchCheckedOut');
	}
	if (!branchName) {
		throw new Error('branchName is required for isBranchCheckedOut');
	}

	const worktrees = await getWorktrees(projectRoot);
	const worktree = worktrees.find((wt) => wt.branch === branchName);
	return worktree ? worktree.path : null;
}

View on GitHub (pinned to c0c98d367c)

Solutions

1. Pass the branch name to check: await isBranchCheckedOut(root, 'feature/x')
2. Derive the current branch first: await getCurrentBranch(root)
3. Fail fast upstream if the branch variable is empty

Example fix

// before
const path = await isBranchCheckedOut(root, process.env.BRANCH);
// after
const branch = process.env.BRANCH || (await getCurrentBranch(root));
if (!branch) throw new Error('No branch specified');
const path = await isBranchCheckedOut(root, branch);

if (!branchName || typeof branchName !== 'string') throw new Error('A branch name is required');
const branch = branchName || (await getCurrentBranch(projectRoot));

function isBranchName(v: unknown): v is string {
  return typeof v === 'string' && v.trim().length > 0 && !v.includes(' ');
}

try {
  const path = await isBranchCheckedOut(root, branch);
} catch (err) {
  if (err.message.includes('branchName is required')) {
    branch = await getCurrentBranch(root);
    return isBranchCheckedOut(root, branch);
  }
  throw err;
}

When it happens

Trigger: Calling isBranchCheckedOut(root, '') or (root, undefined) — commonly when the branch name comes from an unset env var, a parsed-but-empty CLI flag, or a variable that was never assigned.

Common situations: CI pipelines where the branch variable is only set on push events (not on tag builds); scripts reading git branch output that failed silently upstream.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• projectRoot is required for isBranchCheckedOut
• projectRoot is required for isGitRepository
• projectRoot is required for getCurrentBranch
• projectRoot is required for getLocalBranches
• projectRoot is required for getRemoteBranches

AI-assisted analysis of eyaltoledano/claude-task-master@c0c98d367c (2026-08-29). Data as JSON: /api/errors/1947611e19d58c89. Report an issue: GitHub.