What causes "MCP gateway attach is only supported on Unix hosts" in astrid-runtime/astrid?

Run the attach command on a Unix host (Linux or macOS).

MCP gateway attach is only supported on Unix hosts

Error message

MCP gateway attach is only supported on Unix hosts

What it means

`astrid mcp attach` is implemented only for Unix hosts, where the gateway multiplexes over Unix domain sockets. On non-Unix targets (e.g. Windows) a stub `gateway::run` is compiled in that unconditionally fails with this error.

Source

Thrown at crates/astrid-cli/src/commands/mcp/mod.rs:52

//! config, so a stray diagnostic can never corrupt the protocol stream.

// The persistent gateway uses Unix-domain sockets. Keep those implementations
// out of non-Unix builds while preserving the CLI command surface with an
// actionable unsupported-target error.
#[cfg(unix)]
mod attach;
#[cfg(not(unix))]
mod attach {
    use std::path::Path;
    use std::process::ExitCode;

    use anyhow::Result;

    pub(crate) async fn run(
        _principal: Option<&str>,
        _workspace: Option<&Path>,
    ) -> Result<ExitCode> {
        anyhow::bail!("MCP gateway attach is only supported on Unix hosts")
    }
}
mod elicit;
mod form_elicitation;
#[cfg(unix)]
mod gateway;
#[cfg(unix)]
mod idle;
#[cfg(not(unix))]
mod gateway {
    use std::process::ExitCode;

    use anyhow::Result;

    pub(crate) async fn run(_principal: Option<&str>) -> Result<ExitCode> {
        anyhow::bail!("MCP gateway is only supported on Unix hosts")
    }
}

View on GitHub (pinned to affd8760f4)

Solutions

Run the attach command on a Unix host (Linux or macOS).
Use WSL2 on Windows to access the Unix-only MCP gateway functionality.
Do not script attach on non-Unix hosts; gate automation on `cfg!(unix)`-equivalent checks.
If Unix support in a new environment is needed, request/implement a non-Unix transport backend.

Example fix

// before (PowerShell on Windows)
astrid mcp attach
// after (WSL2)
wsl astrid mcp attach

Defensive patterns

Strategy: validation

Validate before calling

#[cfg(not(unix))]
compile_error!("or at runtime:");
if !cfg!(unix) {
    eprintln!("mcp attach requires a Unix host");
    return;
}

Type guard

fn supports_mcp_attach() -> bool { cfg!(unix) }

Try / catch

match attach().await {
    Err(e) if e.to_string().contains("only supported on Unix hosts") =>
        eprintln!("rerun under Linux/macOS or WSL2"),
    other => other?,
}

Prevention

Gate MCP automation on Unix platforms
Use WSL2 on Windows machines
Pin CI jobs that use mcp attach to Linux runners
Check cfg!(unix) before offering the command in tooling

When it happens

Trigger: Invoking `astrid mcp attach` (the run in the non-unix stub of crates/astrid-cli/src/commands/mcp/mod.rs) on a non-Unix platform such as Windows.

Common situations: Running the astrid CLI on Windows or another non-Unix OS; running in a Windows container or a target where the `#[cfg(unix)]` modules are excluded.

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 astrid-runtime/astrid@affd8760f4 (2026-09-09). Data as JSON: /api/errors/cf41de69f36c110b. Report an issue: GitHub.