Unsupported operating system for self-upgrade (only macOS/Li

Error message

Unsupported operating system for self-upgrade (only macOS/Linux supported)

What it means

Self-upgrade is only implemented for macOS and Linux; this error is returned when the upgrade command runs on any other operating system.

Source

Thrown at src/upgrade.rs:158

        if cfg!(target_arch = "x86_64") {
            return Ok("x86_64-apple-darwin");
        }
        if cfg!(target_arch = "aarch64") {
            return Ok("aarch64-apple-darwin");
        }
        bail!("Unsupported macOS architecture");
    }
    if cfg!(target_os = "linux") {
        if cfg!(target_arch = "x86_64") {
            return Ok("x86_64-unknown-linux-gnu");
        }
        if cfg!(target_arch = "aarch64") {
            return Ok("aarch64-unknown-linux-gnu");
        }
        bail!("Unsupported Linux architecture");
    }

    bail!("Unsupported operating system for self-upgrade (only macOS/Linux supported)");
}

fn detect_legacy_platform() -> Result<(&'static str, &'static str)> {
    let os = if cfg!(target_os = "macos") {
        "darwin"
    } else if cfg!(target_os = "linux") {
        "linux"
    } else {
        bail!("Unsupported operating system for self-upgrade (only macOS/Linux supported)");
    };

    let arch = if cfg!(target_arch = "aarch64") {
        "arm64"
    } else if cfg!(target_arch = "x86_64") {
        "amd64"
    } else {
        bail!("Unsupported architecture");
    };

View on GitHub (pinned to a747e741ae)

Solutions

Upgrade manually by downloading the release for your platform
Use the package manager appropriate for the OS

Example fix

// before
flow upgrade
// after
# on Windows, manually:
# download the release asset from https://github.com/<owner>/<repo>/releases and replace the binary

Defensive patterns

Strategy: validation

Validate before calling

if !(cfg!(target_os = "macos") || cfg!(target_os = "linux")) {
    eprintln!("self-upgrade only supports macOS/Linux; use manual download from GitHub releases");
    return;
}

Try / catch

match flow::upgrade::run() {
    Err(e) if e.to_string().contains("Unsupported operating system") => {
        eprintln!("manual upgrade required on this OS");
    }
    Err(e) => eprintln!("upgrade failed: {e}"),
    Ok(()) => {}
}

Prevention

Gate self-upgrade commands behind an OS check in CLI help or startup.
On Windows/BSD, always use the package manager or manual download path.
Use WSL on Windows to get the Linux code path.
Keep CI matrices limited to macOS/Linux so binaries aren't built for untested targets.

When it happens

Trigger: Calling the self-upgrade `run` flow on any platform where both `cfg!(target_os = "macos")` and `cfg!(target_os = "linux")` are false.

Common situations: Running the binary natively on Windows, FreeBSD, or inside unusual cross-compilation targets and attempting a self-upgrade.

Understand the failure class

Background: "unsupported platform" / "not supported on this platform" errors: what they mean and how to fix them — this error's family across 47 libraries.

Related errors

AI-assisted analysis of nikivdev/code@a747e741ae (2026-09-01). Data as JSON: /api/errors/0d4416fd0c412580. Report an issue: GitHub.