gitbutlerapp/gitbutler · error

Setup required: {message} - run `but setup` to configure the

Error message

Setup required: {message} - run `but setup` to configure the project

What it means

In the legacy single-branch flow (feature flag single_branch), init_ctx interactively offers project setup via prompt_project_setup. When the user declines (SetupPromptResult::Declined) at the initial project-lookup site, initialization aborts and directs the user to run `but setup` explicitly.

Source

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

                                    app_settings.clone(),
                                )?;
                                let mut guard = ctx.exclusive_worktree_access();
                                crate::command::legacy::setup::repo(
                                    &mut ctx,
                                    &args.current_dir,
                                    out,
                                    guard.write_permission(),
                                )?;
                                // Retry finding the project after setup
                                LegacyProject::find_by_worktree_dir(workdir).map_err(|_| {
                                    anyhow::anyhow!(
                                        "Setup completed but project still not found at {}",
                                        workdir.display()
                                    )
                                })?
                            }
                            SetupPromptResult::Declined => {
                                anyhow::bail!(
                                    "Setup required: {message} - run `but setup` to configure the project"
                                );
                            }
                        }
                    }
                };

                // Check project setup, prompt for setup if needed
                let mut ctx =
                    Context::new_from_legacy_project_and_settings(&project, app_settings.clone())?;
                {
                    let mut guard = ctx.exclusive_worktree_access();
                    if let Err(e) = check_project_setup(&ctx, guard.read_permission()) {
                        let message = e.to_string();
                        match prompt_for_setup(out, &message) {
                            SetupPromptResult::RunSetup => {
                                // Run setup to fix the project configuration
                                crate::command::legacy::setup::repo(

View on GitHub (pinned to caf1f223d3)

Solutions

1. Run `but setup` and complete the configuration
2. Re-run the original command and accept the setup prompt this time

match run_but(args) {
    Err(e) if e.to_string().contains("Setup required") => {
        run_but(["setup"])?; // complete configuration
        run_but(args)          // retry once
    }
    r => r,
}

When it happens

Trigger: Answering no to the interactive setup prompt of any workspace command while the single_branch feature flag is enabled and the worktree is not yet registered as a legacy project.

Common situations: First run on a new clone with legacy mode enabled, declining a keychain/permission prompt, scripted runs where a stray 'n' on stdin answers the prompt.

Related errors

• Failed to add project after cloning.
• No authenticated Bitbucket users found. Run 'but config forg
• Failed to fetch project: {status} - {error_text}
• Interactive setup requires a terminal. Use `but agent setup
• Not currently on a gitbutler/* branch.

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