unknown history.sync mode

Error message

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

What it means

SyncMode::parse maps the configured history.sync string to one of three modes: sync, fetch-only, or manual. Any other value is rejected with this error so an unrecognized mode never silently disables syncing. The error names the offending value and lists the valid options.

Solutions

Set history.sync in your configuration to exactly one of: sync, fetch-only, or manual
Check for typos and use hyphens not underscores (fetch-only, not fetch_only)
Check the schema/docs for the current release in case the mode name changed between versions

Example fix

# before (mise.toml)
[history]
sync = "fetch_only"
# after
[history]
sync = "fetch-only"

Defensive patterns

Strategy: validation

Validate before calling

const SYNC_MODES = ["sync", "fetch-only", "manual"];
if (!SYNC_MODES.includes(settings.history.sync)) {
  throw new Error(`history.sync must be one of ${SYNC_MODES.join(", ")}`);
}

Type guard

function isSyncMode(v: string): v is "sync" | "fetch-only" | "manual" {
  return ["sync", "fetch-only", "manual"].includes(v);
}

Try / catch

match SyncMode::parse(&value) {
    Ok(mode) => mode,
    Err(e) => {
        eprintln!("{e}; falling back to SyncMode::Manual");
        SyncMode::Manual
    }
}

Prevention

Use the JSON schema / editor validation for your config file so invalid enum values are flagged
Only copy mode names from the current version's docs, not older blog posts
Prefer `mise config` or schema-validated edits over hand-editing settings

When it happens

Trigger: Calling SyncMode::parse (or SyncMode::current, which parses the value from Settings::history.sync) with a string other than "sync", "fetch-only", or "manual" — e.g. a typo like "fetch_only" or "off".

Common situations: Typos or wrong separators in mise.toml settings (underscore vs hyphen); copying a mode name from an older or newer version of the tool where the enum differed; editing settings by hand without the JSON schema.

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

Appendix: 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 533346cc37)