global configuration branch differs from the transferred…

Error message

global configuration branch differs from the transferred branch

What it means

When updating an existing global-configuration checkout (`update` mode), mise requires the destination's current branch to equal the branch of the repository being installed. `git symbolic-ref --short HEAD` in the destination is compared to the branch resolved from the transferred checkout; a mismatch aborts because a fast-forward across different branches is not possible.

Solutions

Switch the destination to the transferred branch: `git -C <destination> checkout <branch>`.
If the source branch was renamed, update the destination's remote-tracking ref and checkout the new branch, then retry.
Align branch conventions across machines so the transferred branch matches the checked-out branch everywhere.
Retry the install after the destination's HEAD branch matches.

Example fix

// before
$ git -C ~/.config/mise symbolic-ref --short HEAD
master
// transfer branch is main

// after
$ git -C ~/.config/mise checkout main

Defensive patterns

Strategy: validation

Validate before calling

const branch = execSync(`git -C ${dest} symbolic-ref --short HEAD`).toString().trim();
if (branch !== expectedBranch) throw new Error(`checkout ${expectedBranch} in ${dest} (currently ${branch})`);

Try / catch

try {
  await installSource(bundle, origin, { update: true });
} catch (e) {
  if (/branch differs/.test(String(e.cause ?? e))) {
    execSync(`git -C ${dest} checkout ${expectedBranch}`);
    return installSource(bundle, origin, { update: true });
  }
  throw e;
}

Prevention

Keep all machines on the same default branch of the config repo
When renaming the default branch, update every checkout (git branch -m + remote tracking)
Avoid leaving the config checkout on feature branches; do branch work in clones

When it happens

Trigger: install/install_source/preview_source (install_at) with update enabled where the destination is checked out on a different branch than the transferred repository's HEAD branch (e.g. destination on `main`, transfer on `master` or a feature branch).

Common situations: The source repo renamed its default branch (`master`→`main`) or switched branches; the destination was left on an old/experimental branch; different machines onboarded at different times when the default branch differed.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

AI-assisted analysis of jdx/mise@533346cc37 (2026-09-17). Data as JSON: /api/errors/89bdc6c5b708254b. Report an issue: GitHub.

Appendix: source

Thrown at src/system/remote_repository.rs:261

    git(
        &checkout,
        &["-c", "core.hooksPath=/dev/null", "checkout", &branch],
    )?;
    if destination.join(".git").exists() {
        if git(destination, &["remote", "get-url", "origin"])? != origin {
            bail!("global configuration origin does not match");
        }
        if !git(
            destination,
            &["status", "--porcelain", "--untracked-files=no"],
        )?
        .is_empty()
        {
            bail!("global configuration has uncommitted changes");
        }
        if update {
            if git(destination, &["symbolic-ref", "--short", "HEAD"])? != branch {
                bail!("global configuration branch differs from the transferred branch");
            }
            if dry_run {
                // the bundle holds the history from the checkout's commit on,
                // so the fast-forward is checked there without fetching into
                // the destination
                let head = git(destination, &["rev-parse", "HEAD"])?;
                if head == revision {
                    miseprintln!(
                        "Would keep {shown} at {revision}, already the transferred revision"
                    );
                } else if git(&checkout, &["merge-base", "--is-ancestor", &head, revision]).is_ok()
                {
                    miseprintln!("Would fast-forward {shown} from {head} to {revision}");
                } else {
                    bail!(
                        "global configuration at {shown} cannot be fast-forwarded to the transferred revision"
                    );
                }

View on GitHub (pinned to 533346cc37)