gitbutlerapp/gitbutler · error

This metadata backend doesn't support branch stack order

Error message

This metadata backend doesn't support branch stack order

What it means

Default implementation of WorkspaceMetadata::set_branch_stack_order: backends that cannot persist the ordered refs of an ad-hoc/single-branch stack deliberately fail with this message instead of silently dropping the order. The trait ships a capability probe, can_persist_branch_stack_order() (default false), so callers can avoid the failure entirely. Hitting it means set was called on a backend that never overrode the default.

Source

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

    /// 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 2497b8007a)

Solutions

1. Guard the call: if meta.can_persist_branch_stack_order() { meta.set_branch_stack_order(&branches)?; } and otherwise keep the order in memory only.
2. Switch to the metadata backend that persists stack order (the standard workspace backend).
3. If you own the backend, implement set_branch_stack_order and return true from can_persist_branch_stack_order.

Example fix

// before
meta.set_branch_stack_order(&branches)?;

// after
if meta.can_persist_branch_stack_order() {
    meta.set_branch_stack_order(&branches)?;
} else {
    // session-only fallback: keep the order without persisting
    session_order = Some(branches.to_vec());
}

if meta.can_persist_branch_stack_order() {
    meta.set_branch_stack_order(&branches)?;
} // else: keep order in memory only

fn can_persist_order(meta: &dyn WorkspaceMetadata) -> bool {
    meta.can_persist_branch_stack_order()
}

match meta.set_branch_stack_order(&branches) {
    Err(err) if err.to_string().contains("doesn't support branch stack order") => {
        // expected on lightweight backends: degrade silently
    }
    r => r?,
}

When it happens

Trigger: Calling set_branch_stack_order on any backend that keeps the default — lightweight, in-memory, or test backends — without first checking can_persist_branch_stack_order().

Common situations: Custom or embedded but_core metadata backends implementing only the required methods; test doubles; new call sites written against the full workspace backend and reused against a simpler one.

Related errors

• Stack has no ID
• DefaultTargetNotFound
• Invalid trailer format, expected `key: value`

AI-assisted analysis of gitbutlerapp/gitbutler@2497b8007a (2026-08-17). Data as JSON: /api/errors/5094da5a71edeba7. Report an issue: GitHub.