gitbutlerapp/gitbutler · error

Could not find a segment named

Error message

Could not find a segment named '{}' in workspace

What it means

When creating a reference with an anchor (`anchor_ref`) that positions the new branch, the workspace must contain a segment matching the anchor. If `find_segment_and_stack_by_refname` finds nothing, create_reference cannot resolve the anchor commit and bails.

Solutions

  1. Pick an anchor ref that is currently applied in the workspace (check workspace segments first)
  2. Apply the anchor branch to the workspace before creating the reference on top of it
  3. Fix the anchor refname (verify it exists in the workspace listing)

Example fix

// before
create_reference(meta, repo, "new-branch", target, anchor: "old-branch")?;
// after
assert!(workspace.find_segment_and_stack_by_refname("refs/heads/old-branch").is_some());
create_reference(meta, repo, "new-branch", target, anchor: "old-branch")?;
Defensive patterns

Strategy: validation

Validate before calling

if workspace.find_segment_and_stack_by_refname(anchor_ref.as_ref()).is_none() {
    return Err(format!("anchor {} not in workspace", anchor_ref.shorten()));
}

Type guard

fn is_workspace_segment(ws: &Workspace, r: &gix::refs::Reference) -> bool {
    ws.find_segment_and_stack_by_refname(r.as_ref()).is_some()
}

Try / catch

match create_reference(...) {
    Err(e) if e.to_string().contains("Could not find a segment named") => /* choose a valid anchor */,
    Err(e) => return Err(e.into()),
    Ok(r) => r,
}

Prevention

When it happens

Trigger: Calling `create_reference` with `anchor_ref` set to a refname that is not part of the target workspace — e.g. a branch on another workspace, an unapplied branch, or a typo.

Common situations: Anchoring a new branch on a branch that was since unapplied or deleted; using a fully-qualified ref from outside the current workspace; UI/script passing stale branch names.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

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

Appendix: source

Thrown at crates/but-workspace/src/branch/create_reference.rs:328

                position,
            }) => {
                let mut validate_id = true;
                let ref_target_id = if workspace.has_metadata() {
                    let (stack_idx, seg_idx) =
                        workspace.try_find_segment_owner_indexes_by_refname(anchor_ref.as_ref())?;
                    let segment = &workspace.stacks[stack_idx].segments[seg_idx];

                    workspace
                        .tip_commit_by_segment_id(segment.id)
                        .map(|commit| position.resolve_commit(commit.into(), ws_base))
                        .context(
                            "BUG: we should always see through to the base or eligible commits",
                        )??
                } else {
                    let Some((_stack, segment)) =
                        workspace.find_segment_and_stack_by_refname(anchor_ref.as_ref())
                    else {
                        bail!(
                            "Could not find a segment named '{}' in workspace",
                            anchor_ref.shorten()
                        );
                    };
                    position.resolve_commit(
                        segment
                            .commits
                            .first()
                            .context("Cannot create reference on unborn branch")?
                            .into(),
                        ws_base,
                    )?
                };
                let points_to_workspace_base = Some(ref_target_id) == ws_base;
                if points_to_workspace_base {
                    validate_id = false;
                }
                // The lower bound owns no commits, so an ad-hoc workspace needs explicit ref

View on GitHub (pinned to 58e5313667)