astrid-runtime/astrid · error

MCP gateway cleanup is only supported on Unix hosts

Error message

MCP gateway cleanup is only supported on Unix hosts

What it means

Sentinel guard in the non-Unix stub module: gc() always fails because gateway lifecycle (socket probes, PID handling) is only implemented behind #[cfg(unix)]; the caller invoked a Unix-only cleanup subcommand on a non-Unix host.

Source

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

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;
mod watch;

#[allow(unused_imports)]
pub(crate) use attach::run as attach;
#[allow(unused_imports)]
pub(crate) use gateway::run as gateway;
#[allow(unused_imports)]
pub(crate) use lifecycle::{gc, ready, stop_gateway};

View on GitHub (pinned to affd8760f4)

Solutions

  1. Run `astrid mcp gc` on Linux or macOS (or WSL2).
  2. Clean up orphaned processes manually on Windows via Task Manager / `taskkill` filtering astrid MCP processes.
  3. Move scheduled cleanup jobs to a Unix runner.
  4. Request Windows support for process reaping.

Example fix

// before (Task Scheduler on Windows)
astrid mcp gc
// after
wsl -e astrid mcp gc
Defensive patterns

Strategy: fallback

Validate before calling

if !cfg!(unix) {
    eprintln!("mcp gc is Unix-only; clean up processes manually on this host");
}

Type guard

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

Try / catch

match gc() {
    Err(e) if e.to_string().contains("cleanup is only supported on Unix") =>
        eprintln!("run gc from a Unix host or reap processes manually"),
    other => other?,
}

Prevention

When it happens

Trigger: Invoking `astrid mcp gc` on Windows or another non-Unix host.

Common situations: Scheduled cleanup tasks in Windows Task Scheduler; Windows CI maintenance jobs reaping orphaned MCP processes.

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