What causes "This metadata backend doesn't support branch stack order" in gitbutlerapp/gitbutler?

Check backend.can_persist_branch_stack_order() before calling set_branch_stack_order and skip persistence when false

This metadata backend doesn't support branch stack order

Error message

This metadata backend doesn't support branch stack order

What it means

This error is the default trait-method implementation for MetadataBackend::set_branch_stack_order. Backends that cannot persist the ordered local branch refs of an ad-hoc/single-branch stack (tip to base) inherit this bail. Callers must check can_persist_branch_stack_order() first.

Solutions

Check backend.can_persist_branch_stack_order() before calling set_branch_stack_order and skip persistence when false
Use a metadata backend implementation that overrides set_branch_stack_order with real persistence
Keep the branch order in memory or in a separate store when the backend cannot persist it

Example fix

// before
backend.set_branch_stack_order(&branches)?;
// after
if backend.can_persist_branch_stack_order() {
    backend.set_branch_stack_order(&branches)?;
}

Defensive patterns

Strategy: validation

Validate before calling

if backend.can_persist_branch_stack_order() {
    backend.set_branch_stack_order(&branches)?;
}

Prevention

Always gate order persistence behind can_persist_branch_stack_order()
Read the trait-method docs: default impls bail by design
Keep a memory fallback when the backend cannot persist

When it happens

Trigger: Calling set_branch_stack_order on a metadata backend whose can_persist_branch_stack_order() returns false (e.g. a backend that only stores workspace state without branch-order persistence).

Common situations: Persisting the order of an ad-hoc or single-branch stack with a metadata backend that does not support branch ordering; forgetting to consult can_persist_branch_stack_order() before writing order.

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

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

Appendix: source

Thrown at crates/but-core/src/lib.rs:262

    /// Implementations that don't persist branch stack order can return `Ok(None)`.
    ///
    /// This is best-effort: the returned refs may include entries for branches that no longer
    /// exist if pruning hasn't run since they were deleted (see
    /// [`Self::remove_missing_branch_stack_order_references`]). Callers must treat the result as a
    /// hint and validate each ref against the repository, ignoring any that don't resolve, rather
    /// than assuming every entry is live.
    fn branch_stack_order(
        &self,
        _ref_name: &gix::refs::FullNameRef,
    ) -> anyhow::Result<Option<Vec<gix::refs::FullName>>> {
        Ok(None)
    }

    /// Persist the ordered local branch refs for an ad-hoc/single-branch stack, from tip to base.
    ///
    /// Implementations that don't persist branch stack order should return an error.
    fn set_branch_stack_order(&mut self, _branches: &[gix::refs::FullName]) -> anyhow::Result<()> {
        anyhow::bail!("This metadata backend doesn't support branch stack order")
    }

    /// Return `true` if this backend can persist ad-hoc/single-branch stack order.
    fn can_persist_branch_stack_order(&self) -> bool {
        false
    }

    /// Rename a local branch ref in persisted ad-hoc/single-branch stack order metadata.
    ///
    /// Implementations that don't persist branch stack order can ignore this.
    fn rename_branch_stack_order_reference(
        &mut self,
        _old_ref_name: &gix::refs::FullNameRef,
        _new_ref_name: &gix::refs::FullNameRef,
    ) -> anyhow::Result<()> {
        Ok(())
    }

View on GitHub (pinned to 58e5313667)