GitButler mode exit required: please run `but teardown` to p

Error message

GitButler mode exit required: please run `but teardown` to preserve your work.

What it means

check_workspace_commits_before_init detects commits made directly on top of the gitbutler/workspace branch. Such commits sit outside GitButler's virtual-branch model and operating on that state could lose work, so after printing a warning every command aborts until `but teardown` exits GitButler mode cleanly while preserving the work.

Source

Thrown at crates/but/src/setup.rs:555

            writeln!(writer)?;
            writeln!(
                writer,
                "{}",
                theme::get()
                    .attention
                    .paint("⚠ Detected commits on top of gitbutler/workspace")
            )?;
            writeln!(writer)?;
            writeln!(
                writer,
                "{}",
                theme::get().hint.paint("GitButler detected that you have committed directly on the\ngitbutler/workspace branch. To preserve your work and\nfix up things, please run `but teardown`.")
            )?;
            writeln!(writer)?;
        }

        // After teardown, we should not continue with the original command
        anyhow::bail!(
            "GitButler mode exit required: please run `but teardown` to preserve your work."
        );
    }

    Ok(())
}

View on GitHub (pinned to caf1f223d3)

Solutions

Run `but teardown` - it preserves the work and exits GitButler mode
After teardown, re-run `but setup` if you want to re-enter GitButler mode
Prevent recurrence: commit through GitButler's own flow, never directly on gitbutler/workspace

Defensive patterns

Strategy: validation

Validate before calling

#!/bin/sh
branch=$(git symbolic-ref --short HEAD 2>/dev/null || true)
if [ "$branch" = "gitbutler/workspace" ]; then
  echo "run `but teardown` before continuing" >&2; exit 1
fi
# safe to run but commands

Try / catch

let out = cmd.output()?;
if !out.status.success() && String::from_utf8_lossy(&out.stderr).contains("but teardown") {
    // safety stop: surface to the user, never force past it
}

Prevention

Never commit directly while gitbutler/workspace is checked out
Wrap scripted but usage with a checked-branch guard
Treat this abort as a safety stop - run but teardown, do not work around it

When it happens

Trigger: Committing manually while gitbutler/workspace is checked out (e.g. plain `git commit` on that branch), then running any but command with workspace checks enabled (WorkspaceCheck::Enabled).

Common situations: Users switching branches with plain git inside a GitButler-managed repo, IDEs auto-committing on the checked-out workspace branch, following generic git tutorials inside a GitButler project.

Related errors

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