{"record":{"id":"0fd9c77ad63d2c30","repo":"jdx/mise","slug":"cannot-synchronize-reason","errorCode":null,"errorMessage":"cannot synchronize: {reason}","messagePattern":"cannot synchronize: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/cli/dotfiles/sync.rs","lineNumber":45,"sourceCode":"impl DotfilesSync {\n    pub(crate) async fn run(self) -> Result<()> {\n        match self.sync().await {\n            Ok(()) => Ok(()),\n            Err(err) if self.best_effort && is_network_failure(&err) => {\n                warn!(\"history sync: {err:#}\");\n                Ok(())\n            }\n            Err(err) => Err(err),\n        }\n    }\n\n    async fn sync(&self) -> Result<()> {\n        if !crate::config::Settings::get().history.enabled {\n            bail!(\"history is disabled (history.enabled = false)\");\n        }\n        let (store, tracked, _) = super::history::open().await?;\n        if let Some(reason) = store.unavailable() {\n            bail!(\"cannot synchronize: {reason}\");\n        }\n        let outcome = run::sync(&store, &tracked, &SyncRequest::new(self.fetch_only))?;\n        crate::system::history::sync::origin::report(&outcome);\n        Ok(())\n    }\n}\n\nfn is_network_failure(error: &eyre::Report) -> bool {\n    error\n        .downcast_ref::<crate::system::history::sync::network::NetworkError>()\n        .is_some()\n}\n\n#[cfg(test)]\nmod tests {\n    use super::*;\n\n    #[test]","sourceCodeStart":27,"sourceCodeEnd":63,"githubUrl":"https://github.com/jdx/mise/blob/afd2eddd3a50c16190efc1c7e94404b48f72af57/src/cli/dotfiles/sync.rs#L27-L63","documentation":"After confirming history is enabled, sync opens the history store and checks `store.unavailable()`; if the store reports a problem, sync aborts with 'cannot synchronize: {reason}'. The concrete cause is always in the reason string.","triggerScenarios":"`dotfiles sync` runs while the history Store is unavailable: state dir missing/unreadable, backend unsupported, store locked or corrupted.","commonSituations":"Read-only filesystem or missing state directory; history state created by an incompatible mise version; concurrent operation holding the store.","solutions":["Read the `{reason}` and fix the underlying store problem","Check permissions on mise's state directory","Wait for/recover any in-flight history operation (operation lock)","Run `mise doctor` and, if corrupted, reset the dotfiles history store"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"mise bootstrap dotfiles status >/dev/null 2>&1 || echo 'history store unavailable for sync'","typeGuard":null,"tryCatchPattern":"if ! mise bootstrap dotfiles sync 2>&1; then\n  echo \"sync aborted; inspect 'cannot synchronize' reason and mise doctor\"\nfi","preventionTips":["Verify state dir health/permissions before scripted syncs","Serialize history operations; don't run sync concurrently with capture wrappers","Upgrade mise as one unit so store schema stays compatible"],"tags":["cli","dotfiles","storage","sync"],"backgroundTag":"file-write-failed","analyzedSha":"afd2eddd3a50c16190efc1c7e94404b48f72af57","analyzedAt":"2026-09-09T01:38:25.179Z","contentChangedAt":"2026-09-09T01:38:25.179Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}