gitbutlerapp/gitbutler · error · anyhow::Error

Cannot position reference below unborn segment '{}'

Error message

Cannot position reference below unborn segment '{}'

What it means

While positioning a new/updated reference with create_reference, the code needed the oldest commit of the target segment (to anchor a 'below' placement) but the segment has no commits and no resolvable tip — an unborn segment. References cannot be placed below a segment that contains nothing.

Source

Thrown at crates/but-transaction/src/lib.rs:568

                            but_workspace::branch::create_reference::Anchor::AtReference {
                                ref_name,
                                position,
                            },
                        ),
                        None,
                    )
                } else {
                    let oldest_commit_id = segment
                        .commits
                        .last()
                        .map(|commit| commit.id)
                        .or_else(|| {
                            workspace
                                .tip_commit_by_segment_id(segment.id)
                                .map(|commit| commit.id)
                        })
                        .ok_or_else(|| {
                            anyhow::anyhow!(
                                "Cannot position reference below unborn segment '{}'",
                                ref_name.shorten()
                            )
                        })?;
                    (
                        Some(but_workspace::branch::create_reference::Anchor::AtSegment {
                            ref_name,
                            position,
                        }),
                        Some(oldest_commit_id),
                    )
                }
            }
            anchor => (anchor, None),
        };
        let repo = self.repo().clone();
        let branch_stack_orders = self
            .inner

View on GitHub (pinned to caf1f223d3)

Solutions

1. Anchor the reference above the segment or against an explicit commit instead of Position::Below
2. Create the first commit on the target segment before placing references below it
3. If metadata looks wrong, reload/recompute the workspace graph so the segment's tip resolves

// ensure the anchor segment actually has a commit before requesting a 'below' position
let has_commits = segment.commits.iter().any(|_| true)
    || workspace.tip_commit_by_segment_id(segment.id).is_some();
if !has_commits {
    return Err(anyhow!("segment unborn — cannot place ref below; anchor above or by commit"));
}

fn segment_is_born(ws: &but_graph::Workspace, segment_id: SegmentId) -> bool {
    ws.tip_commit_by_segment_id(segment_id).is_some()
}

match create_ref(...) {
    Err(e) if e.to_string().contains("unborn segment") => { /* fall back to Anchor::AtSegment { position: Above } or AtCommit */ }
    r => r,
}

When it happens

Trigger: Calling reference creation/update with an anchor position Below against a segment that is empty (newly created branch whose first commit doesn't exist yet, or a segment whose tip lookup in workspace metadata returned None).

Common situations: Creating dependent branches in an order that leaves the anchor segment unborn (e.g. trying to insert a ref below a just-created empty branch); workspace metadata out of sync with the graph so tip_commit_by_segment_id finds nothing.

Related errors

• When using Anthropic in a bring your own key configuration,
• HTTP Error ${response.statusText}: ${text}
• Failed to find reference {target} in rebase editor
• Ad-hoc (single-branch) branch moves are not supported inside
• cannot mix operations that require `materialize` and `materi

AI-assisted analysis of gitbutlerapp/gitbutler@caf1f223d3 (2026-08-20). Data as JSON: /api/errors/157ca43815538497. Report an issue: GitHub.