cannot onboard this setup repository: history is unavailable

Error message

cannot onboard this setup repository: history is unavailable: {reason}

What it means

After confirming via an isolated probe that the remote is a marked setup repository, from_git opens the real local Store. If that store is unavailable — the local history backend cannot operate, typically because git is missing or the local state directory cannot be initialized — onboarding cannot proceed and the error carries the underlying reason.

Solutions

Install/repair git and confirm `git --version` works, then retry onboarding
Fix the {reason} reported for the local store — e.g. repair or reinitialize the history state directory and check its permissions
Re-run the tool in an environment where the state directory is writable (correct HOME/user, adequate disk space)

Example fix

# before (in restricted CI)
$ mise history onboard https://host/org/repo.git
Error: cannot onboard this setup repository: history is unavailable: git executable not found
# after (image config)
RUN apt-get update && apt-get install -y git
$ mise history onboard https://host/org/repo.git  # succeeds

Defensive patterns

Strategy: try-catch

Validate before calling

// verify prerequisites for the real local store
if which("git").is_err() { return Err("git is required"); }
let dir = history_state_dir()?;
std::fs::create_dir_all(&dir)?; // surfaces permission/disk errors early

Try / catch

match Outcome::from_git(url) {
    Err(e) if e.to_string().contains("history is unavailable") => {
        eprintln!("{e}");
        repair_or_reinit_local_history_store()?;
        Outcome::from_git(url)
    }
    other => other,
}

Prevention

Ensure git is installed on end-user machines and CI images
Keep the history state directory writable by the running user and monitor disk space
After failed runs or permission changes, validate the local store before retrying onboarding

When it happens

Trigger: Calling from_git when Store::open() then store.unavailable() returns Some(reason): git missing/broken on the actual environment (as opposed to the probe), unwritable or corrupted local history state directory, incompatible store version.

Common situations: git not installed on the user's machine; history state directory corrupted or owned by another user after a permission change; running in a sandbox/CI without required tooling; disk-full state dir.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

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

Appendix: source

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

    // Detect marked repositories without creating persistent tracking state
    // for users of the released, ordinary --adopt workflow.
    let probe_dir = tempfile::tempdir()?;
    let store = Store::open_in(probe_dir.path())?;
    if let Some(reason) = store.unavailable() {
        bail!("cannot determine whether {url} is a setup repository: {reason}");
    }
    let repo = store
        .repo()
        .ok_or_else(|| eyre::eyre!("probing a setup repository requires git"))?;
    let Some(branch) = default_branch(&Remote::new(repo, url))? else {
        return Ok(None);
    };
    if !matches!(probe(&store, url, &branch)?, RepoState::Marked(_)) {
        return Ok(None);
    }
    let store = Store::open()?;
    if let Some(reason) = store.unavailable() {
        bail!("cannot onboard this setup repository: history is unavailable: {reason}");
    }
    refuse_other_connection(&store, url, &branch)?;
    let outcome = run(
        &store,
        &Onboarding {
            fetch_from: url.to_string(),
            origin: url.to_string(),
            branch,
            yes,
            dry_run,
            replace_history,
        },
    )
    .await?;
    Ok(Some(outcome))
}

/// The branch a fresh machine takes: the repository's default branch (its

View on GitHub (pinned to 533346cc37)