What causes "branch does not exist: ${branchName}" in eyaltoledano/claude-task-master?

Verify the name with `git branch --list feature/x` (check for typos).

branch does not exist: ${branchName}

Error message

branch does not exist: ${branchName}

What it means

checkoutBranch() verifies the target branch exists via branchExists() and throws when it does not. The library will not auto-create branches on checkout; use createBranch/createAndCheckoutBranch for that. After the existence check it would also require a clean tree unless options.force is true.

Source

Thrown at packages/tm-core/src/modules/git/adapters/git-adapter.ts:440

	 *
	 * @param {string} branchName - Name of branch to checkout
	 * @param {Object} options - Checkout options
	 * @param {boolean} options.force - Force checkout even with uncommitted changes
	 * @returns {Promise<void>}
	 * @throws {Error} If branch doesn't exist or working tree is dirty (unless force=true)
	 *
	 * @example
	 * await git.checkoutBranch('feature-branch');
	 * await git.checkoutBranch('feature-branch', { force: true });
	 */
	async checkoutBranch(
		branchName: string,
		options: { force?: boolean } = {}
	): Promise<void> {
		// Check if branch exists
		const exists = await this.branchExists(branchName);
		if (!exists) {
			throw new Error(`branch does not exist: ${branchName}`);
		}

		// Ensure clean working tree unless force is specified
		if (!options.force) {
			await this.ensureCleanWorkingTree();
		}

		// Checkout the branch
		const checkoutOptions = options.force ? ['-f', branchName] : [branchName];
		await this.git.checkout(checkoutOptions);
	}

	/**
	 * Creates a new branch and checks it out.
	 * Convenience method combining createBranch and checkoutBranch.
	 *
	 * @param {string} branchName - Name for the new branch
	 * @returns {Promise<void>}

View on GitHub (pinned to c0c98d367c)

Solutions

Verify the name with `git branch --list feature/x` (check for typos).
Create it if intended: use createAndCheckoutBranch('feature/x').
If it exists only on the remote, create a local tracking branch: git checkout -b feature/x origin/feature/x (or git fetch first).
Fetch remotes to refresh refs: git fetch --all before retrying.

Example fix

// before
await git.checkoutBranch('feature/x'); // throws if missing
// after
if (await git.branchExists('feature/x')) {
  await git.checkoutBranch('feature/x');
} else {
  await git.createAndCheckoutBranch('feature/x');
}

Defensive patterns

Strategy: validation

Validate before calling

if (!(await git.branchExists('feature/x'))) {
  // create it or fetch remote tracking branch first
}

Try / catch

try {
  await git.checkoutBranch('feature/x');
} catch (e) {
  if (e instanceof Error && e.message.startsWith('branch does not exist')) {
    await git.createAndCheckoutBranch('feature/x'); // or create local tracking branch
    return;
  }
  throw e;
}

Prevention

Verify branch names with `git branch --list` before automation runs.
Run git fetch before checkout if the branch may exist only on the remote.
Use createAndCheckoutBranch() when you intend to create, not checkoutBranch().
Pass { force: true } only when you also intend to skip the clean-tree requirement.

When it happens

Trigger: Calling gitAdapter.checkoutBranch('feature/x') (or startWorkflow flows that switch to a branch) when 'feature/x' was never created, was deleted locally, or only exists on a remote without a local tracking branch.

Common situations: Typo in branch name; switching machines after fresh clone where the branch is only origin/feature/x; branch deleted after merge; expecting checkout to create the branch like `git checkout -b`.

Related errors

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