gitbutlerapp/gitbutler · error

Local branch ' ' not found

Error message

Local branch '{}' not found

What it means

`but branch update` resolves its target branch through resolve_local_branch, which first normalizes the name to a full ref and looks it up in the repository. This error is thrown when no reference with that name exists in the repo.

Solutions

1. Check the exact branch name with `but branch list` or `git branch`.
2. If it only exists on the remote, create it locally first (e.g. `git switch <branch>` or `git checkout -b <branch> origin/<branch>`).
3. Fix any typo and re-run the command.

Example fix

// before
but branch update featuer-x --to abc123
// after
but branch update feature-x --to abc123

const branches = execSync('git branch --list ' + shellEscape(name)).toString().trim();
if (!branches) throw new Error(`Local branch '${name}' does not exist; check 'git branch' before updating`);

try {
  execSync(`but branch update ${name} --to ${sha}`, { stdio: 'inherit' });
} catch (err) {
  if (String(err).includes('not found')) {
    console.error(`Branch ${name} not found; run 'git branch' to list local branches`);
  } else { throw err; }
}

When it happens

Trigger: Running `but branch update <name> ...` where try_find_reference returns None after normalizing to refs/heads/<name> — the branch doesn't exist locally (typo, never created, or only exists on a remote).

Common situations: Typos in branch names; branches that exist only as remote-tracking refs (origin/feature) and were never checked out locally; branches deleted locally but still pushed.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Branch ' ' not found
• Branch ' ' not found when checking for conflicts
• Branch " " has no conflicted commits.
• Branch ' ' not found. Available branches
• Cannot apply non-existing branch

AI-assisted analysis of gitbutlerapp/gitbutler@58e5313667 (2026-09-18). Data as JSON: /api/errors/9b9184153cd2d099. Report an issue: GitHub.

Appendix: source

Thrown at crates/but/src/command/branch/update.rs:138

                        commits: commits.into_iter().map(Into::into).collect(),
                        message,
                    }
                }
                but_workspace::branch::InteractiveIntegrationStep::Merge { commit_id } => {
                    json::InteractiveIntegrationStep::Merge {
                        commit_id: commit_id.into(),
                    }
                }
            })
            .collect(),
    }
}

fn resolve_local_branch(ctx: &but_ctx::Context, branch: &str) -> anyhow::Result<FullName> {
    let candidate = normalize_local_branch_ref(branch)?;
    let repo = ctx.repo.get()?;
    let Some(reference) = repo.try_find_reference(candidate.as_ref())? else {
        bail!("Local branch '{}' not found", candidate.shorten());
    };
    let reference = reference.detach();
    match reference.name.category() {
        Some(Category::LocalBranch) => Ok(reference.name),
        Some(Category::RemoteBranch) => {
            bail!(
                "Expected a local branch, but '{}' is a remote-tracking branch",
                reference.name.shorten()
            )
        }
        _ => bail!(
            "Expected a local branch, but '{}' is not under refs/heads/",
            reference.name.shorten()
        ),
    }
}

fn normalize_local_branch_ref(branch: &str) -> anyhow::Result<FullName> {

View on GitHub (pinned to 58e5313667)