gitbutlerapp/gitbutler · error

Attempted to update the symbolic reference

Error message

Attempted to update the symbolic reference {name}

What it means

When the rebase finalizes reference updates, it inspects each existing reference's target. Peel/symbolic references (e.g. a branch pointing at another ref like HEAD or a symref) cannot be rewritten to a concrete commit id, so the library bails instead of clobbering the symref. Only direct (object-id) targets are updated.

Solutions

1. Convert the symbolic reference to a direct reference (git update-ref with the commit oid) before rebasing.
2. Detach HEAD or un-attach the branch so the reference is a plain object-id ref.
3. Inspect `git for-each-ref` to find which ref is symbolic and normalize it.

Example fix

// before: refs/heads/feature -> symbolic ref refs/heads/other
// after
git update-ref refs/heads/feature <commit-oid>

// Check the ref is direct before rebasing
git for-each-ref --format='%(refname) %(objecttype)' refs/heads/ | grep -v ' commit$'

match rebase_result {
    Err(e) if e.to_string().contains("Attempted to update the symbolic reference") => {
        // extract ref name, run `git update-ref <ref> <oid>`, retry
    }
    other => other?,
}

When it happens

Trigger: Rebasing with a Reference step that resolves to a symbolic reference (TargetRef::Symbolic), such as a virtual branch stored as a symref pointing to another ref, when the rebase tries to update it.

Common situations: Workspaces where a branch was converted into a symref (e.g. checked out HEAD attached to the branch); tooling that rewrote refs as symbolic; mixing git CLI operations with GitButler virtual branches.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• Remote HEAD for is not symbolic
• A matching parent can't be found in the output graph
• A parent in the output graph is not a pick
• An edge with desired order
• Base commit must exist if provided

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

Appendix: source

Thrown at crates/but-rebase/src/graph_rebase/rebase.rs:143

                        let reference = self.repo.try_find_reference(&refname)?;

                        if let Some(reference) = reference {
                            let target = reference.target();
                            match target {
                                gix::refs::TargetRef::Object(id) => {
                                    if id == to_reference {
                                        unchanged_references.push(refname.clone());
                                    } else {
                                        ref_edits.push(RefEdit::update(
                                            refname.clone(),
                                            to_reference,
                                            PreviousValue::MustExistAndMatch(target.into()),
                                            "",
                                        ));
                                    }
                                }
                                gix::refs::TargetRef::Symbolic(name) => {
                                    bail!("Attempted to update the symbolic reference {name}");
                                }
                            }
                        } else {
                            ref_edits.push(RefEdit::update(
                                refname.clone(),
                                to_reference,
                                PreviousValue::MustNotExist,
                                "",
                            ));
                        }
                    }

                    output_graph.add_node(Step::Reference { refname, mutable })
                }
                Step::None => output_graph.add_node(Step::None),
            };

            graph_mapping.insert(step_idx, new_idx);

View on GitHub (pinned to 58e5313667)