gitbutlerapp/gitbutler · error

No push remote set or more than one remote

Error message

No push remote set or more than one remote

What it means

When no target branch is configured yet, default_target_setting_if_none guesses the default target by asking the repo for the default push remote (equivalent to `git symbolic-ref refs/remotes/origin/HEAD --short`). gix's remote_default_name returns None when there is no push remote or the choice is ambiguous (more than one remote), so this error is thrown. A unique default remote is required to derive the workspace's target branch.

Solutions

  1. Add or fix a single push remote: `git remote add origin <url>` (remove extra remotes or set remote.pushDefault).
  2. Set the default explicitly: `git config remote.pushDefault origin` so the default remote is unambiguous.
  3. Configure the target branch in the GitButler project settings so default_target_setting_if_none has nothing to guess.

Example fix

// before: ambiguous remotes
$ git remote -v
upstream  ...
fork      ...

// after
$ git config remote.pushDefault upstream
# or configure the GitButler target explicitly
Defensive patterns

Strategy: validation

Validate before calling

let remotes = repo.remotes()?;
if remotes.len() != 1 && repo.config_snapshot(None)?.get("remote.pushDefault").is_err() {
    anyhow::bail!("set remote.pushDefault or configure the GitButler target explicitly");
}

Try / catch

match default_target_setting_if_none(ctx) {
    Err(e) if e.to_string().contains("No push remote set or more than one remote") => {
        // fix git remotes / remote.pushDefault, then retry
    }
    other => other?,
}

Prevention

When it happens

Trigger: prepare_handle_changes runs on a project whose ProjectMeta has no target_ref, and repo.remote_default_name(Push) returns None because the repo has zero remotes or multiple remotes with no uniquely dominant push remote.

Common situations: A freshly cloned repo with no remote configured; a repo with both 'origin' and 'upstream' (or multiple fork remotes) where the default cannot be inferred; a local-only sandbox repo used for testing.

Understand the failure class

Background: "missing required config value" errors: why libraries refuse to start when a configuration key is empty, unset, or blank — this error's family across 48 libraries.

Related errors

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

Appendix: source

Thrown at crates/but-action/src/lib.rs:149

                .project_meta()?
                .target_ref_or_err()?
                .to_string()
                .parse()?;
            gitbutler_branch_actions::set_base_branch(ctx, &target_ref, perm).map(|_| ())
        }
    }
}

fn default_target_setting_if_none(ctx: &Context) -> anyhow::Result<()> {
    if ctx.project_meta()?.target_ref.is_some() {
        return Ok(());
    }
    // Lets do the equivalent of `git symbolic-ref refs/remotes/origin/HEAD --short` to guess the default target.

    let repo = ctx.repo.get()?;
    let remote_name = repo
        .remote_default_name(gix::remote::Direction::Push)
        .ok_or_else(|| anyhow::anyhow!("No push remote set or more than one remote"))?
        .to_string();

    let mut head_ref = repo
        .find_reference(&format!("refs/remotes/{remote_name}/HEAD"))
        .map_err(|_| anyhow::anyhow!("No HEAD reference found for remote {remote_name}"))?;
    let target_ref_name = head_ref
        .target()
        .try_name()
        .ok_or_else(|| anyhow::anyhow!("Remote HEAD for {remote_name} is not symbolic"))?
        .to_owned();

    let head_commit = head_ref.peel_to_commit()?;

    ctx.set_project_meta(ProjectMeta {
        target_ref: Some(target_ref_name),
        target_commit_id: Some(head_commit.id),
        push_remote: None,
    })?;

View on GitHub (pinned to 58e5313667)