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 creates a temporary store and fetches all refs from the local history repository to snapshot it. If the underlying git fetch command exits non-zero, the snapshot cannot be produced, so the library bails with this error rather than previewing incomplete history.

Source

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

/// 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 afd2eddd3a)

Solutions

Ensure the source history repository has refs (git for-each-ref) — an empty repo cannot be snapshotted.
Re-run git fetch with the same file URL manually to see the underlying git error and fix it.
Check permissions on the temp directory and the source repository path.
Confirm git is installed and functional (git --version) since preview requires git.

Example fix

// ensure source has refs before preview
if repo.for_each_ref()?.is_empty() {
    eyre::bail!("source history repository has no refs to preview");
}
let copied = destination.network(["fetch", "--no-tags", url.as_str(), "+refs/*:refs/*"])?;

Defensive patterns

Strategy: try-catch

Validate before calling

// check source repo has refs and git works before preview
assert!(Path::new(&source.dir()).join(".git").exists() || source.dir().join("HEAD").exists());
let has_refs = !repo.for_each_ref()?.is_empty();

Try / catch

match preview_store(&source) {
    Err(e) if e.to_string().contains("could not snapshot") => {
        eprintln!("snapshot fetch failed; run the fetch manually to see git's error");
    }
    other => other?,
}

Prevention

Ensure the history repository has at least one ref before previewing.
Keep git installed and healthy where the preview runs.
Check temp-dir permissions and disk space.
Run the equivalent fetch by hand to diagnose the underlying git failure.

When it happens

Trigger: The `git fetch --no-tags <file-url> +refs/*:refs/*` spawned in preview_store fails (non-zero status) — e.g. the source repo has no refs, the file-path URL is wrong, or git itself is broken/absent in the temp store.

Common situations: Running onboarding preview against an empty or freshly initialized history repository with no refs to copy; filesystem permission problems on the temp dir; a corrupted or partially initialized source repository.

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@afd2eddd3a (2026-09-09). Data as JSON: /api/errors/f2ea401997e93ebf. Report an issue: GitHub.