jdx/mise · error

GitHub relay requires Linux or macOS

Error message

GitHub relay requires Linux or macOS

What it means

Thrown by the remote bootstrap command when a GitHub relay is requested (`github_relay` options produce `Some(relay)`) but the build/platform is not unix (Windows). The relay implementation only supports Linux and macOS, so mise refuses to start the remote bootstrap with relay enabled.

Source

Thrown at src/cli/bootstrap.rs:3043

impl BootstrapRemote {
    async fn run(mut self) -> Result<()> {
        normalize_adopt_alias(&mut self.adopt, self.from_git.take());
        crate::ui::ctrlc::exit_on_ctrl_c(false);
        let relay = crate::github_relay::Scope::from_flags(
            self.github_relay_read_only,
            &self.github_relay_repo,
            self.github_relay_all_repos,
        )?;
        let relay = crate::github_relay::configure(
            relay,
            self.github_relay_log_requests,
            self.github_relay_no_log_requests,
            self.github_relay_log_format.as_deref(),
            self.github_relay_max_duration.as_deref(),
        )?;
        if relay.is_some() && !cfg!(unix) {
            bail!("GitHub relay requires Linux or macOS");
        }
        if self.connect_timeout == 0 {
            bail!("--connect-timeout must be greater than zero");
        }
        let config = Config::get().await?;
        let config_excludes = system::remote::excludes_from_config(&config);
        let inventory = system::remote::hosts_from_config(&config, &config_excludes)?;
        let mut selected = select_remote_inventory(&inventory, &self.targets, self.all, &self.tag)?;
        let ad_hoc_source = self.source.clone().unwrap_or(std::env::current_dir()?);
        for destination in &self.host {
            let host =
                system::remote::ad_hoc_host(destination, ad_hoc_source.clone(), &config_excludes)?;
            if selected.insert(host.name.clone(), host).is_some() {
                bail!("remote target '{destination}' was selected more than once");
            }
        }
        if selected.is_empty() {
            if inventory.is_empty() {

View on GitHub (pinned to afd2eddd3a)

Solutions

  1. Run the remote bootstrap from a Linux or macOS machine (or WSL, which reports unix).
  2. Drop the GitHub relay flags and configure GitHub access on the remote hosts directly (tokens/ssh).
  3. Use a Linux CI runner for relay-enabled bootstrap runs.

Example fix

// before (Windows)
mise bootstrap remote --github-relay ... --host deploy@example.com
// after (WSL/Linux)
wsl mise bootstrap remote --github-relay ... --host deploy@example.com
Defensive patterns

Strategy: validation

Validate before calling

case "$(uname -s)" in
  Linux|Darwin) relay_flags=("--github-relay" "on") ;;
  *) relay_flags=() ; echo "github relay unsupported here; skipping" ;;
esac
mise bootstrap remote "${relay_flags[@]}" --host deploy@example.com

Try / catch

if [[ "$(uname -s)" != Linux && "$(uname -s)" != Darwin ]]; then
  echo "run from Linux/macOS or configure remote GitHub access without relay" >&2
  exit 1
fi

Prevention

When it happens

Trigger: Running a remote bootstrap command with `--github-relay ...` (and any of the relay log/format/duration options) on a non-unix platform, where `cfg!(unix)` evaluates to false.

Common situations: Windows developers attempting to relay GitHub access to remote bootstrap hosts; WSL quirk resolved by using native Linux; CI images on Windows attempting relay-enabled bootstrap.

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