could not snapshot the local history repository for preview

Error message

could not snapshot the local history repository for preview

What it means

preview_store builds a throwaway preview of the history repository by fetching all refs from the local source repository into a temp store via a git network fetch. If the underlying git fetch exits nonzero, the library cannot produce a preview snapshot and bails with this message. The real git stderr is handled by the network layer; this error marks the preview step as failed.

Solutions

Run `git fsck` in the source history repository to detect corruption and repair or reinstall its history
Retry the onboarding preview after clearing locks (remove stale .lock files) and confirming disk space/permissions
Inspect git output by running the equivalent fetch manually to see the underlying failure, then address that specific cause

Example fix

// preview_store does:
let copied = destination.network(["fetch", "--no-tags", url.as_str(), "+refs/*:refs/*"])?;
if !copied.status.success() {
    bail!("could not snapshot the local history repository for preview");
}
// manual diagnosis:
// git -C <source> fsck && git -C <probe-store> fetch --no-tags <source-path> '+refs/*:refs/*'

Defensive patterns

Strategy: fallback

Validate before calling

// preflight: source repo must be a healthy git repo
if !source.dir().join(".git").exists() && !run_git(&["-C", source, "rev-parse", "--git-dir"]).success() {
    return Err("source history repository is not a valid git repo");
}

Try / catch

match preview_store(&source) {
    Ok((temp, preview)) => preview,
    Err(e) if e.to_string().contains("could not snapshot") => {
        repair_source_repo(&source)?; // fsck, clear locks
        preview_store(&source)?
    }
    Err(e) => return Err(e),
}

Prevention

Run `git fsck` periodically on history repositories
Avoid concurrent writes/reads of the source repo while previewing
Ensure adequate disk space and permissions in the temp directory used for previews

When it happens

Trigger: Calling preview_store (via run during onboarding) when the `git fetch --no-tags <file-url> +refs/*:refs/*` into the temp store fails — e.g. git is unavailable (already handled earlier), the source repo path can't be addressed, refspec conflicts, or a corrupted source repository.

Common situations: Source history repository with corrupted or locked object files; a destination store already containing conflicting refs; filesystem/permission problems in the temp directory; git fetch rejecting the +refs/*:refs/* mapping due to an unexpected ref layout.

Understand the failure class

Background: "git command failed": what it means when a tool shells out to git and git exits non-zero — this error's family across 21 libraries.

Related errors

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

Appendix: source

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

/// All fetches, reconciliation, and preview status writes then target this
/// private store, so cancellation never needs to roll back live bookkeeping.
fn preview_store(store: &Store) -> Result<(tempfile::TempDir, Store)> {
    let _sync = run::lock(store)?;
    let _capture = store.lock()?;
    let temp = tempfile::tempdir()?;
    hstore::ensure_store_dir_in(temp.path())?;
    let preview = Store::open_in(temp.path())?;
    let source = store
        .repo()
        .ok_or_else(|| eyre::eyre!("preview requires git"))?;
    let destination = preview
        .repo()
        .ok_or_else(|| eyre::eyre!("preview requires git"))?;
    let url = url::Url::from_file_path(source.dir())
        .map_err(|_| eyre::eyre!("cannot address the local history repository"))?;
    let copied = destination.network(["fetch", "--no-tags", url.as_str(), "+refs/*:refs/*"])?;
    if !copied.status.success() {
        bail!("could not snapshot the local history repository for preview");
    }
    run::write_status(temp.path(), &run::read_status(store.state_dir())?)?;
    // Reopen to rebuild the derived history index from the copied commits.
    let preview = Store::open_in(temp.path())?;
    Ok((temp, preview))
}

fn preview_configuration(store: &Store) -> Result<tempfile::TempDir> {
    let temp = tempfile::tempdir()?;
    let repo = store
        .repo()
        .ok_or_else(|| eyre::eyre!("preview requires git"))?;
    let head = repo
        .ref_oid(UPSTREAM_REF)?
        .ok_or_else(|| eyre::eyre!("setup preview has no fetched branch"))?;
    let encrypted = super::files::encrypted_paths(repo, Some(&head))?;
    let tracked = crate::system::history::manifest::Manifest::read(repo, &head)?
        .ok_or_else(|| eyre::eyre!("setup repository has no enrollment metadata"))?

View on GitHub (pinned to 533346cc37)