unknown history.sync mode {other:?}; use sync, fetch-only, o

Error message

unknown history.sync mode {other:?}; use sync, fetch-only, or manual

What it means

`SyncMode::parse` in src/system/history/sync/mod.rs validates the `settings.history.sync` value against exactly three accepted strings: `sync`, `fetch-only`, and `manual`. Any other value is rejected with this error listing the valid options. The mode controls what the background watcher does automatically: `sync` publishes/fetches/applies, `fetch-only` never publishes, and `manual` performs no automatic network activity.

Source

Thrown at src/system/history/sync/mod.rs:57

    /// No automatic network activity: `sync` and `pull` on request only.
    Manual,
}

/// What a mode does in the background.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(crate) struct Automatic {
    pub publish: bool,
    pub fetch: bool,
    pub apply: bool,
}

impl SyncMode {
    pub(crate) fn parse(value: &str) -> Result<Self> {
        match value {
            "sync" => Ok(Self::Sync),
            "fetch-only" => Ok(Self::FetchOnly),
            "manual" => Ok(Self::Manual),
            other => bail!("unknown history.sync mode {other:?}; use sync, fetch-only, or manual"),
        }
    }

    pub(crate) fn current() -> Result<Self> {
        Self::parse(&crate::config::Settings::get().history.sync)
    }

    pub(crate) fn as_str(self) -> &'static str {
        match self {
            Self::Sync => "sync",
            Self::FetchOnly => "fetch-only",
            Self::Manual => "manual",
        }
    }

    pub(crate) fn publishes(self) -> bool {
        self != Self::FetchOnly
    }

View on GitHub (pinned to afd2eddd3a)

Solutions

Set `history.sync` to one of the exact accepted values: `sync`, `fetch-only`, or `manual` (e.g. `mise settings set history.sync fetch-only`).
Fix the value in your settings file/config (check spelling, hyphens, and lowercase).
Run `mise settings` or consult the history.sync docs to confirm the allowed enum values for your mise version.

Example fix

// before (settings)
history.sync = "FetchOnly"

// after
history.sync = "fetch-only"

Defensive patterns

Strategy: validation

Validate before calling

const VALID_MODES: [&str; 3] = ["sync", "fetch-only", "manual"];
fn validate_sync_mode(v: &str) -> bool {
    VALID_MODES.contains(&v)
}

Try / catch

// Rust
match SyncMode::parse(&value) {
    Ok(mode) => use(mode),
    Err(e) => eprintln!("{} — set history.sync to sync | fetch-only | manual", e),
}

Prevention

Copy mode values exactly: `sync`, `fetch-only` (hyphen, lowercase), `manual`
Use `mise settings edit` or schema-validated config so invalid enum values are caught at edit time
After changing the mode, run a command that reads settings (e.g. `mise settings get history.sync`) to confirm it parses

When it happens

Trigger: Calling `SyncMode::parse(value)` or `SyncMode::current()` (which parses `Settings::get().history.sync`) with a string other than "sync", "fetch-only", or "manual" — e.g. a misspelled or wrongly-cased mode like "Sync", "fetch_only", or "auto" in settings.

Common situations: Typo in mise settings (`mise settings set history.sync fetchonly` instead of `fetch-only`); copying a mode name from another tool; using an underscore instead of a hyphen; a stale settings file from an older version with a now-removed mode value.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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