jdx/mise · error

dotfiles: cannot save the baseline: {reason}

Error message

dotfiles: cannot save the baseline: {reason}

What it means

After successful tracking, mise saves a baseline checkpoint of the newly tracked files. If the history Store reports itself unavailable, track aborts with 'cannot save the baseline: {reason}' so the user knows enrollment succeeded but the initial snapshot did not.

Source

Thrown at src/cli/dotfiles/track.rs:367

                .find(|invalid| invalid.path == display_path(&path))
                .map(|invalid| invalid.reason.clone())
                .unwrap_or_else(|| "the declaration was not loaded".into());
            bail!("dotfiles: {key} could not be tracked: {reason}");
        }
    }
    baseline(&tracked, declared).await
}

/// Saves the baseline checkpoint of newly tracked paths; a failure fails
/// the enrollment, since an untracked file must never look protected.
async fn baseline(tracked: &TrackedSet, declared: &[(String, PathBuf)]) -> Result<()> {
    if !crate::config::Settings::get().history.enabled {
        warn!("dotfiles: history is disabled (history.enabled = false); no baseline saved");
        return Ok(());
    }
    let store = Store::open()?;
    if let Some(reason) = store.unavailable() {
        bail!("dotfiles: cannot save the baseline: {reason}");
    }
    // A capture wrapper owns the operation lock until this child exits. It
    // reloads enrollment and explicitly saves all current tracked files in
    // its outcome (including manual entries), or during interruption recovery.
    if let Some(parent) = std::env::var_os(crate::system::history::scope::ENV_VAR)
        && crate::system::history::store::read_marker_in(&crate::dirs::STATE)?.is_some_and(
            |marker| {
                marker.kind == crate::system::history::store::OperationKind::Capture
                    && parent == std::ffi::OsStr::new(&marker.uuid)
            },
        )
    {
        info!(
            "dotfiles: enrolled; the enclosing capture will save the baseline when the command finishes"
        );
        return Ok(());
    }
    let names = declared

View on GitHub (pinned to afd2eddd3a)

Solutions

1. Read the `{reason}` and fix the underlying storage problem (permissions, disk, path)
2. Recover/stale-clear the history operation lock (the ENV_VAR capture wrapper), then re-run track or `dotfiles save`
3. Run `mise doctor`; if the store is corrupt, reset the dotfiles history state and re-track

mise bootstrap dotfiles status >/dev/null 2>&1 || echo 'history store unhealthy; baseline will fail'

if ! mise bootstrap dotfiles track ~/target 2>&1; then
  echo "tracked but baseline may have failed; rerun 'dotfiles save' after fixing store"
fi

When it happens

Trigger: `dotfiles track` -> baseline: history enabled, but `Store::open()`-created store returns Some(reason) from `unavailable()` — state dir problems, unsupported backend, corruption.

Common situations: Read-only or missing mise state directory; history store locked by a capture wrapper that died; store schema incompatibility after a mise upgrade.

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}
• cannot synchronize: {reason}
• tracking declarations updated, but could not commit the chan
• invalid checkpoint reference {spec:?}
• no history checkpoint matches {spec:?}

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