{"record":{"id":"94e5fb1ba8cbd70c","repo":"jdx/mise","slug":"cannot-replace-local-history-while-path-s-need-a-decision","errorCode":null,"errorMessage":"cannot replace local history while {} path(s) need a decision; move the conflicting files aside and retry","messagePattern":"cannot replace local history while (.+?) path\\(s\\) need a decision; move the conflicting files aside and retry","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/system/history/sync/onboard.rs","lineNumber":376,"sourceCode":"            miseprintln!(\n                \"Replacing local history {} with origin {}.\",\n                short_oid(&replacement.local),\n                short_oid(&replacement.remote)\n            );\n        }\n        request.capture = false;\n        request.dry_run = false;\n        let result = async {\n            run::sync_locked(store, &tracked, &request)?;\n            let applied = apply::apply_locked_with_scope(\n                store,\n                &tracked,\n                &ApplyRequest::automatic(),\n                Some(operation),\n            )\n            .await?;\n            if applied.held > 0 {\n                bail!(\n                    \"cannot replace local history while {} path(s) need a decision; move the conflicting files aside and retry\",\n                    applied.held\n                );\n            }\n            Ok(applied)\n        }\n        .await;\n        match result {\n            Ok(applied) => applied,\n            Err(error) => {\n                restore_after_failed_replacement(\n                    store,\n                    replacement.as_ref(),\n                    previous_upstream.as_deref(),\n                    &previous_status,\n                    &previous_sync_state,\n                )?;\n                return Err(error);","sourceCodeStart":358,"sourceCodeEnd":394,"githubUrl":"https://github.com/jdx/mise/blob/533346cc374382b41ec5ff70536252b2e96e725c/src/system/history/sync/onboard.rs#L358-L394","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before: conflicting file blocks replace\nmv ~/.gitconfig ~/.gitconfig.local-backup\n// after: retry onboarding\nmise dot origin set <url>","handlingStrategy":"validation","validationCode":"if applied.held > 0 {\n    for path in applied.held_paths {\n        eprintln!(\"resolve held path first: {path}\");\n    }\n    return;\n}","typeGuard":null,"tryCatchPattern":"match outcome {\n    Err(e) if e.to_string().contains(\"path(s) need a decision\") => {\n        eprintln!(\"resolve or back up conflicting files, then retry\");\n    }\n    _ => {}\n}","preventionTips":["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"],"tags":["git","sync","conflict","data-safety"],"backgroundTag":"file-already-exists","analyzedSha":"533346cc374382b41ec5ff70536252b2e96e725c","analyzedAt":"2026-09-17T13:35:38.149Z","contentChangedAt":"2026-09-17T13:35:38.149Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}