{"record":{"id":"b6bff3ed32f47d5e","repo":"eyaltoledano/claude-task-master","slug":"branch-does-not-exist-branchname","errorCode":null,"errorMessage":"branch does not exist: ${branchName}","messagePattern":"branch does not exist: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/tm-core/src/modules/git/adapters/git-adapter.ts","lineNumber":440,"sourceCode":"\t *\n\t * @param {string} branchName - Name of branch to checkout\n\t * @param {Object} options - Checkout options\n\t * @param {boolean} options.force - Force checkout even with uncommitted changes\n\t * @returns {Promise<void>}\n\t * @throws {Error} If branch doesn't exist or working tree is dirty (unless force=true)\n\t *\n\t * @example\n\t * await git.checkoutBranch('feature-branch');\n\t * await git.checkoutBranch('feature-branch', { force: true });\n\t */\n\tasync checkoutBranch(\n\t\tbranchName: string,\n\t\toptions: { force?: boolean } = {}\n\t): Promise<void> {\n\t\t// Check if branch exists\n\t\tconst exists = await this.branchExists(branchName);\n\t\tif (!exists) {\n\t\t\tthrow new Error(`branch does not exist: ${branchName}`);\n\t\t}\n\n\t\t// Ensure clean working tree unless force is specified\n\t\tif (!options.force) {\n\t\t\tawait this.ensureCleanWorkingTree();\n\t\t}\n\n\t\t// Checkout the branch\n\t\tconst checkoutOptions = options.force ? ['-f', branchName] : [branchName];\n\t\tawait this.git.checkout(checkoutOptions);\n\t}\n\n\t/**\n\t * Creates a new branch and checks it out.\n\t * Convenience method combining createBranch and checkoutBranch.\n\t *\n\t * @param {string} branchName - Name for the new branch\n\t * @returns {Promise<void>}","sourceCodeStart":422,"sourceCodeEnd":458,"githubUrl":"https://github.com/eyaltoledano/claude-task-master/blob/c0c98d367c55296bfe69e65680625b6db437af02/packages/tm-core/src/modules/git/adapters/git-adapter.ts#L422-L458","documentation":"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.","triggerScenarios":"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.","commonSituations":"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`.","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."],"exampleFix":"// before\nawait git.checkoutBranch('feature/x'); // throws if missing\n// after\nif (await git.branchExists('feature/x')) {\n  await git.checkoutBranch('feature/x');\n} else {\n  await git.createAndCheckoutBranch('feature/x');\n}","handlingStrategy":"validation","validationCode":"if (!(await git.branchExists('feature/x'))) {\n  // create it or fetch remote tracking branch first\n}","typeGuard":null,"tryCatchPattern":"try {\n  await git.checkoutBranch('feature/x');\n} catch (e) {\n  if (e instanceof Error && e.message.startsWith('branch does not exist')) {\n    await git.createAndCheckoutBranch('feature/x'); // or create local tracking branch\n    return;\n  }\n  throw e;\n}","preventionTips":["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."],"tags":["git","branch","not-found"],"backgroundTag":"branch-not-found","analyzedSha":"c0c98d367c55296bfe69e65680625b6db437af02","analyzedAt":"2026-08-29T02:56:26.071Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}