What causes "MCP gateway socket path has no parent" in astrid-runtime/astrid?

Fix the runtime home / socket directory configuration.

MCP gateway socket path has no parent

Error message

MCP gateway socket path has no parent

What it means

`prepare_gateway_socket` resolves the gateway Unix socket path, ensures its parent directory exists with private permissions, and cleans up stale sockets. This error is thrown when the socket path has no parent directory — an invariant guard against a degenerate path (bare root), since the socket path always derives from the runtime home.

Source

Thrown at crates/astrid-cli/src/commands/mcp/lifecycle.rs:379

        format!(
            "failed to create private runtime directory {}",
            path.display()
        )
    })?;
    #[cfg(unix)]
    {
        use std::os::unix::fs::PermissionsExt;
        std::fs::set_permissions(path, std::fs::Permissions::from_mode(0o700))?;
    }
    Ok(())
}

/// Bind-time cleanup and endpoint ownership check for a gateway listener.
pub(crate) async fn prepare_gateway_socket(_lifecycle: &GatewayLifecycleLock) -> Result<PathBuf> {
    let path = gateway_socket_path()?;
    let parent = path
        .parent()
        .ok_or_else(|| anyhow::anyhow!("MCP gateway socket path has no parent"))?;
    ensure_private_dir(parent)?;

    if path.exists() {
        if UnixStream::connect(&path).await.is_ok() {
            anyhow::bail!("MCP gateway is already running at {}", path.display());
        }
        // The lifecycle lock excludes every gateway generation. If the
        // pathname survived a crash, this holder is now the only process that
        // may remove and replace it.
        std::fs::remove_file(&path).with_context(|| {
            format!(
                "failed to remove stale MCP gateway socket {}",
                path.display()
            )
        })?;
    }
    Ok(path)
}

View on GitHub (pinned to affd8760f4)

Solutions

Fix the runtime home / socket directory configuration.
Rerun with default configuration.
Report as a bug if stock settings trigger it.

Example fix

// before
ASTRID_RUNTIME_HOME=/ astrid mcp gateway run
// after
ASTRID_RUNTIME_HOME=$HOME/.local/share/astrid astrid mcp gateway run

Defensive patterns

Strategy: validation

Validate before calling

let home = std::env::var("ASTRID_RUNTIME_HOME").unwrap_or_default();
assert!(home != "/" && !home.is_empty(), "runtime home must be a normal directory");

Type guard

fn has_parent(p: &std::path::Path) -> bool { p.parent().is_some() }

Try / catch

match prepare_gateway_socket(&lifecycle).await {
    Err(e) if e.to_string().contains("has no parent") => eprintln!("bad socket path configuration"),
    Err(e) => return Err(e),
    Ok(path) => bind(path).await?,
}

Prevention

Keep the socket inside a normal runtime home directory
Avoid filesystem-root path overrides
Validate socket path configuration at startup
Report occurrences with default config as bugs

When it happens

Trigger: The socket path (`mcp-gateway.sock`) resolves with no parent, i.e. runtime home configured to `/` or empty, or broken path construction.

Common situations: Runtime home misconfigured to the filesystem root; library bug in socket-path derivation. Not expected normally.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — 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/9bd774cb940dd312. Report an issue: GitHub.