cannot replace local history while

Error message

cannot replace local history while {} path(s) need a decision; move the conflicting files aside and retry

What it means

When onboarding replaces the machine's local history with the repository's, mise first applies files through the conflict-holding mechanism. If any paths are 'held' — i.e. they conflict with local state and need a manual decision — it refuses to replace history rather than destroying uncommitted local data.

Solutions

Move or rename the conflicting files aside so the automatic apply can proceed, then retry
Resolve each held path by accepting or discarding the local change, then re-run
Use the conflict-resolution command to decide each held path individually instead of automatic mode

Example fix

// before: conflicting file blocks replace
mv ~/.gitconfig ~/.gitconfig.local-backup
// after: retry onboarding
mise dot origin set <url>

Defensive patterns

Strategy: validation

Validate before calling

if applied.held > 0 {
    for path in applied.held_paths {
        eprintln!("resolve held path first: {path}");
    }
    return;
}

Try / catch

match outcome {
    Err(e) if e.to_string().contains("path(s) need a decision") => {
        eprintln!("resolve or back up conflicting files, then retry");
    }
    _ => {}
}

Prevention

Commit or back up local dotfile edits before replacing history
Run the apply/conflict check in automatic mode first to preview held paths
Keep a backup of the config directory before onboarding

When it happens

Trigger: from_git -> run with `replace_history` enabled calls apply with ApplyRequest::automatic(); `applied.held > 0` means at least one tracked path conflicts and is awaiting a decision.

Common situations: Local uncommitted edits to tracked dotfiles that differ from the repository versions; locally added files colliding with repository paths; applying history right after editing configs.

Understand the failure class

Background: "already exists" / EEXIST / FileAlreadyExistsException: what the 'file already exists' error means and how to fix it — this error's family across 37 libraries.

Related errors

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

Appendix: source

Thrown at src/system/history/sync/onboard.rs:376

            miseprintln!(
                "Replacing local history {} with origin {}.",
                short_oid(&replacement.local),
                short_oid(&replacement.remote)
            );
        }
        request.capture = false;
        request.dry_run = false;
        let result = async {
            run::sync_locked(store, &tracked, &request)?;
            let applied = apply::apply_locked_with_scope(
                store,
                &tracked,
                &ApplyRequest::automatic(),
                Some(operation),
            )
            .await?;
            if applied.held > 0 {
                bail!(
                    "cannot replace local history while {} path(s) need a decision; move the conflicting files aside and retry",
                    applied.held
                );
            }
            Ok(applied)
        }
        .await;
        match result {
            Ok(applied) => applied,
            Err(error) => {
                restore_after_failed_replacement(
                    store,
                    replacement.as_ref(),
                    previous_upstream.as_deref(),
                    &previous_status,
                    &previous_sync_state,
                )?;
                return Err(error);

View on GitHub (pinned to 533346cc37)