Missing reference which should be known to workspace…

Error message

Missing reference {segment_to_insert_above} which should be known to workspace metadata to serve as insertion position for {rn}

What it means

During apply, when inserting an incoming branch as a new stack segment, the code anchors it above an existing reference (`segment_to_insert_above`). If the workspace-metadata insertion helper returns `None` — meaning that anchor reference is not present in the metadata — apply bails, because it cannot place the branch correctly. This is treated as a bug/unsupported state for now.

Solutions

Refresh/rebuild workspace metadata so the anchor reference is present, then retry apply
Apply the branch with the workspace metadata in a consistent state (close other sessions writing to it)
Report as a bug — the comment in source says this is bailed until automatic handling is worth implementing

Defensive patterns

Strategy: try-catch

Validate before calling

// ensure the anchor exists in workspace metadata
if !ws.segments().any(|s| s.ref_name() == anchor) {
    return Err("anchor missing from workspace metadata; refresh workspace first");
}

Try / catch

match apply(...) {
    Err(e) if e.to_string().contains("Missing reference") => { refresh_metadata(); retry_once(); }
    Err(e) => return Err(e.into()),
    Ok(r) => r,
}

Prevention

Keep workspace metadata in sync; avoid manual git mutations behind the tool's back
Retry apply after a metadata refresh when adhoc workspaces are involved
Treat this as a bug report trigger if it reproduces consistently

When it happens

Trigger: Calling apply on an adhoc workspace where the computed anchor reference (insertion position) for a branch is missing from workspace metadata — e.g. metadata is stale or the anchor branch was dropped during the merge re-computation.

Common situations: Metadata out of sync with the repository after manual `git` operations or a concurrent modification; applying into an adhoc workspace whose reference layout changed between computation and insertion.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

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

Appendix: source

Thrown at crates/but-workspace/src/branch/apply.rs:682

                .find_map(|segment| {
                    segment
                        .commits
                        .iter()
                        .flat_map(|c| c.ref_iter())
                        .find_map(|ambiguous_rn| {
                            (ambiguous_rn == rn.as_ref())
                                .then_some(segment.ref_name())
                                .flatten()
                        })
                })
            {
                match ws_mut.insert_new_segment_above_anchor_if_not_present(
                    rn.as_ref(),
                    segment_to_insert_above,
                ) {
                    None => {
                        // For now bail, until we know it's worth fixing this case automatically.
                        bail!(
                            "Missing reference {segment_to_insert_above} which should be known to workspace metadata to serve as insertion position for {rn}"
                        );
                    }
                    Some(false) => {
                        // The branch already existed, probably as stack, but it didn't come through. Remove it and use the anchor.
                        ws_mut.remove_segment(rn.as_ref());
                        if ws_mut.insert_new_segment_above_anchor_if_not_present(
                            rn.as_ref(),
                            segment_to_insert_above,
                        ) != Some(true)
                        {
                            bail!(
                                "Failed to assure that {rn} is in the workspace as dependent branch after removing it"
                            );
                        }
                    }
                    Some(true) => {}
                }

View on GitHub (pinned to 58e5313667)