What causes "Remote-tracking branch {} does not exist" in gitbutlerapp/gitbutler?

Fetch the remote so the tracking ref is created: `git fetch origin`

Remote-tracking branch

Error message

Remote-tracking branch {} does not exist

What it means

local_tracking_branch first validates that the given remote-tracking reference actually exists in the repository (and is not symbolic). If try_find_validated_ref returns None, the ref name refers to something that isn't in the repo, so deriving a local tracking branch is impossible.

Solutions

Fetch the remote so the tracking ref is created: `git fetch origin`
Verify the ref exists with `git rev-parse refs/remotes/origin/feature` before calling the API
Correct the ref name spelling (compare with `git branch -r`)

Example fix

// before
let b = local_tracking_branch(&repo, "refs/remotes/origin/feature".try_into()?); // fails if never fetched
// after
if repo.try_find_reference("refs/remotes/origin/feature")?.is_some() {
    let b = local_tracking_branch(&repo, "refs/remotes/origin/feature".try_into()?);
}

Defensive patterns

Strategy: validation

Validate before calling

fn tracking_ref_exists(repo: &gix::Repository, r: &gix::refs::FullNameRef) -> bool {
    repo.try_find_reference(r).map(|o| o.is_some()).unwrap_or(false)
}

Try / catch

match result {
    Err(e) if e.to_string().contains("does not exist") => {
        eprintln!("run `git fetch <remote>` to create the tracking ref");
        anyhow::bail!(e);
    }
    other => other,
}

Prevention

Fetch the remote before deriving local tracking branches
Validate ref names against `git branch -r` output
Watch for upstream branch deletions that invalidate cached tracking refs

When it happens

Trigger: Calling local_tracking_branch(repo, remote_tracking_ref) with a FullNameRef like refs/remotes/origin/feature that was never fetched and thus does not exist locally.

Common situations: Referring to a remote branch before `git fetch`; stale references to branches deleted on the remote; typos in the remote-tracking ref name.

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

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

Appendix: source

Thrown at crates/but-workspace/src/branch/mod.rs:597

    }
    let merge_key = gix::config::tree::Branch::MERGE.name;
    if section.value(merge_key).is_none() {
        section.push(merge_key, Some(upstream_branch.as_bstr()))?;
    }
    Ok((config, remote_tracking_commit_id.into()))
}

/// Return the local tracking branch of `remote_tracking_ref`, creating it at the remote-tracking
/// commit with tracking configuration if it doesn't exist yet, like `git checkout <name>` does.
///
/// An existing local tracking branch is returned as is, even if it diverged from the remote.
pub fn local_tracking_branch(
    repo: &gix::Repository,
    remote_tracking_ref: &gix::refs::FullNameRef,
) -> anyhow::Result<gix::refs::FullName> {
    // Symbolic ones, `origin/HEAD` say, would make a local branch of the name they point through.
    if try_find_validated_ref(repo, remote_tracking_ref, "check out")?.is_none() {
        anyhow::bail!(
            "Remote-tracking branch {} does not exist",
            remote_tracking_ref.as_bstr()
        );
    }
    let Some((local_tracking_ref, _remote)) =
        repo.upstream_branch_and_remote_for_tracking_branch(remote_tracking_ref)?
    else {
        anyhow::bail!(
            "Couldn't find remote refspecs that would match {}",
            remote_tracking_ref.as_bstr()
        );
    };
    if repo
        .try_find_reference(local_tracking_ref.as_ref())?
        .is_some()
    {
        return Ok(local_tracking_ref);
    }

View on GitHub (pinned to 58e5313667)