jdx/mise · error

cannot synchronize: {reason}

Error message

cannot synchronize: {reason}

What it means

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.

Source

Thrown at src/cli/dotfiles/sync.rs:45

impl DotfilesSync {
    pub(crate) async fn run(self) -> Result<()> {
        match self.sync().await {
            Ok(()) => Ok(()),
            Err(err) if self.best_effort && is_network_failure(&err) => {
                warn!("history sync: {err:#}");
                Ok(())
            }
            Err(err) => Err(err),
        }
    }

    async fn sync(&self) -> Result<()> {
        if !crate::config::Settings::get().history.enabled {
            bail!("history is disabled (history.enabled = false)");
        }
        let (store, tracked, _) = super::history::open().await?;
        if let Some(reason) = store.unavailable() {
            bail!("cannot synchronize: {reason}");
        }
        let outcome = run::sync(&store, &tracked, &SyncRequest::new(self.fetch_only))?;
        crate::system::history::sync::origin::report(&outcome);
        Ok(())
    }
}

fn is_network_failure(error: &eyre::Report) -> bool {
    error
        .downcast_ref::<crate::system::history::sync::network::NetworkError>()
        .is_some()
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]

View on GitHub (pinned to afd2eddd3a)

Solutions

1. Read the `{reason}` and fix the underlying store problem
2. Check permissions on mise's state directory
3. Wait for/recover any in-flight history operation (operation lock)
4. Run `mise doctor` and, if corrupted, reset the dotfiles history store

mise bootstrap dotfiles status >/dev/null 2>&1 || echo 'history store unavailable for sync'

if ! mise bootstrap dotfiles sync 2>&1; then
  echo "sync aborted; inspect 'cannot synchronize' reason and mise doctor"
fi

When it happens

Trigger: `dotfiles sync` runs while the history Store is unavailable: state dir missing/unreadable, backend unsupported, store locked or corrupted.

Common situations: Read-only filesystem or missing state directory; history state created by an incompatible mise version; concurrent operation holding the store.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

• cannot save: {reason}
• partial pulls are not supported: apply the complete setup wi
• --changed does not accept target arguments
• at least one target or --changed is required
• --source can only be used with one target

AI-assisted analysis of jdx/mise@afd2eddd3a (2026-09-09). Data as JSON: /api/errors/0fd9c77ad63d2c30. Report an issue: GitHub.