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

Run the readiness check from a Unix host that can reach the gateway socket.

MCP gateway readiness is only supported on Unix hosts

Error message

MCP gateway readiness is only supported on Unix hosts

What it means

`astrid mcp ready` checks gateway readiness via Unix sockets, so on non-Unix targets a stub lifecycle::ready always fails with this error. Note the non-Unix stop_gateway stub returns Ok(()) — only readiness is refused.

Source

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

    use anyhow::Result;

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

    use anyhow::Result;

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

    pub(crate) async fn stop_gateway() -> Result<()> {
        Ok(())
    }

    pub(crate) fn gc() -> Result<ExitCode> {
        anyhow::bail!("MCP gateway cleanup is only supported on Unix hosts")
    }
}
mod mrtr;
// Parent-death detection reads `getppid()` (Unix-only); the module and its use
// site are target-gated so the CLI still compiles on non-Unix targets.
#[cfg(unix)]
mod parent_death;
mod readiness;
mod server;
mod session_guard;

View on GitHub (pinned to affd8760f4)

Solutions

Run the readiness check from a Unix host that can reach the gateway socket.
Perform the health check from inside WSL2.
Replace the Windows-hosted check with an HTTP/TCP probe against an exposed endpoint, if available.
Gate readiness polling scripts on the platform (skip on Windows).

Example fix

// before
astrid mcp ready --format json   # on Windows
// after
wsl astrid mcp ready --format json

Defensive patterns

Strategy: fallback

Validate before calling

if !cfg!(unix) {
    eprintln!("readiness probe unavailable on this platform; use an alternate health endpoint");
}

Type guard

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

Try / catch

match ready(principal, format).await {
    Err(e) if e.to_string().contains("readiness is only supported on Unix") =>
        eprintln!("run the readiness check from a Unix host"),
    other => other?,
}

Prevention

Run health checks from hosts that share the Unix socket filesystem
Use WSL2 for local checks on Windows
Provide an alternate HTTP health endpoint for non-Unix monitoring
Skip readiness polling in non-Unix scripts

When it happens

Trigger: Invoking `astrid mcp ready` (any --format) on Windows or another non-Unix host.

Common situations: Health-check scripts run on Windows machines; Windows CI jobs probing a gateway; mixed environments where the CLI runs on the wrong host.

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/cd3cd22c1eedc546. Report an issue: GitHub.