gitbutlerapp/gitbutler · error

Not currently on a gitbutler/* branch.

Error message

Not currently on a gitbutler/* branch.

What it means

Thrown by check_project_setup in crates/but/src/command/legacy/setup.rs:503 when the repository HEAD is not a gitbutler/* branch (gitbutler/workspace or gitbutler/edit). GitButler legacy commands read virtual-branch state relative to the workspace branch, so any other HEAD (a normal branch like main, a detached commit, an unborn branch) fails this precondition immediately.

Source

Thrown at crates/but/src/command/legacy/setup.rs:503

/// If so, returns true
/// Otherwise, returns an error with a message indicating what is not setup.
/// It will check:
/// - if the repository exists
/// - if the project is registered in GitButler
/// - if there is a remote
/// - if there is a default target branch set
/// - if we're on a gitbutler/* branch
pub fn check_project_setup(ctx: &Context, perm: &RepoShared) -> anyhow::Result<bool> {
    let (repo, ws, _) = ctx.workspace_and_db_with_perm(perm)?;

    // check if we're on a gitbutler/* branch
    let head = repo.head()?;
    let head_name = head
        .referent_name()
        .map(|n| n.shorten().to_owned())
        .unwrap_or_default();
    if !head_name.starts_with(b"gitbutler/") {
        anyhow::bail!("Not currently on a gitbutler/* branch.");
    }

    // When on gitbutler/edit, the project was already set up when entering edit mode.
    // The workspace graph built from gitbutler/edit doesn't expose the target ref or
    // remote configuration, but both are still configured in virtual_branches.toml
    // and will be accessible when returning to gitbutler/workspace.
    if head_name == b"gitbutler/edit" {
        return Ok(true);
    }

    // TODO(legacy): it's fine to have no target.
    if ws.graph.project_meta.target_ref.is_none() {
        anyhow::bail!("No default target branch set.");
    }

    // check if there is a remote
    if ws.remote_name().is_none()
        && repo

View on GitHub (pinned to caf1f223d3)

Solutions

1. Run `git checkout gitbutler/workspace` (or `gitbutler/edit`) to re-enter the workspace, then retry the command.
2. If no gitbutler/* branch exists, run `but setup` (or onboarding in the desktop app) to initialize the project.
3. Confirm which workspace branch exists with `git branch -a | grep gitbutler`.
4. If plain Git operation is intended, use `git` directly instead of the workspace-dependent `but` command.

Example fix

# before
git checkout main
but status   # Not currently on a gitbutler/* branch.

# after
git checkout gitbutler/workspace
but status

use gix::prelude::ReferenceExt as _;
let head = repo.head()?;
let name = head.referent_name().map(|n| n.shorten().to_owned()).unwrap_or_default();
if !name.starts_with(b"gitbutler/") {
    anyhow::bail!("switch to gitbutler/workspace before running GitButler commands");
}

match check_project_setup(&ctx, &perm) {
    Ok(set_up) => { /* proceed */ }
    Err(err) if err.to_string().contains("gitbutler/*") => {
        eprintln!("run `git checkout gitbutler/workspace` and retry");
    }
    Err(err) => return Err(err),
}

When it happens

Trigger: Running any legacy `but` command that calls check_project_setup(ctx, perm) while HEAD points elsewhere: after `git checkout main`, after `git checkout <sha>` (detached), in a fresh clone that never went through GitButler setup, or in a linked worktree checked out to a plain branch.

Common situations: User temporarily switched to a plain branch (CI, comparison, IDE integration) and re-ran a GitButler command; repository was never initialized with GitButler so no gitbutler/workspace branch exists; another git tool detached HEAD.

Related errors

• Failed to communicate with LM Studio server: ${error instanc
• Invalid response: ${JSON.stringify(result)}
• When using GitButler's API to summarize code, you must be lo
• When using LM Studio, you must provide a valid endpoint
• When using OpenAI in a bring your own key configuration, you

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