astrid-runtime/astrid · error

MCP attach host session key is empty

Error message

MCP attach host session key is empty

What it means

build_registration reads the host session key from ASTRID_SESSION_ID (falling back to AOS_MCP_SESSION_ID / MCP_SESSION_ID). If the variable is not set at all, the .context() error surfaces; if it is set but blank/whitespace, this explicit error is thrown, since an empty session key would produce an unusable attach registration.

Source

Thrown at crates/astrid-cli/src/commands/mcp/attach.rs:100

}

fn build_registration(
    caller: &astrid_core::PrincipalId,
    workspace: Option<&Path>,
    ready: &super::lifecycle::GatewayReady,
) -> Result<AttachRegistration> {
    let host = std::env::var("ASTRID_HOST")
        .or_else(|_| std::env::var("AOS_MCP_HOST"))
        .or_else(|_| std::env::var("MCP_HOST"))
        .ok()
        .filter(|value| !value.trim().is_empty())
        .unwrap_or_else(|| "aos".to_owned());
    let host_session_id = std::env::var("ASTRID_SESSION_ID")
        .or_else(|_| std::env::var("AOS_MCP_SESSION_ID"))
        .or_else(|_| std::env::var("MCP_SESSION_ID"))
        .context("MCP attach requires the host session key in ASTRID_SESSION_ID")?;
    if host_session_id.trim().is_empty() {
        anyhow::bail!("MCP attach host session key is empty");
    }
    build_registration_with_context(caller, workspace, ready, &host, &host_session_id)
}

fn build_registration_with_context(
    caller: &astrid_core::PrincipalId,
    workspace: Option<&Path>,
    ready: &super::lifecycle::GatewayReady,
    host: &str,
    host_session_id: &str,
) -> Result<AttachRegistration> {
    if host.trim().is_empty() {
        anyhow::bail!("MCP attach host is empty");
    }
    if host_session_id.trim().is_empty() {
        anyhow::bail!("MCP attach host session key is empty");
    }
    let workspace_abs = absolute_workspace(workspace)?;

View on GitHub (pinned to affd8760f4)

Solutions

1. Set ASTRID_SESSION_ID to a non-empty session identifier before attaching
2. Verify no empty override: `echo "[$ASTRID_SESSION_ID]"`
3. Remove blank AOS_MCP_SESSION_ID / MCP_SESSION_ID exports that shadow a valid value

Example fix

// before
export ASTRID_SESSION_ID=
aos mcp attach
// after
export ASTRID_SESSION_ID="sess-8f3c..."
aos mcp attach

let sid = std::env::var("ASTRID_SESSION_ID").unwrap_or_default();
if sid.trim().is_empty() { return Err("ASTRID_SESSION_ID must be a non-empty session key"); }

fn has_session_key() -> bool { std::env::var("ASTRID_SESSION_ID").map(|v| !v.trim().is_empty()).unwrap_or(false) }

match std::env::var("ASTRID_SESSION_ID") {
    Ok(v) if !v.trim().is_empty() => { /* proceed */ }
    _ => return Err(anyhow!("set a non-empty ASTRID_SESSION_ID before mcp attach")),
}

When it happens

Trigger: `aos mcp attach` with ASTRID_SESSION_ID (or fallback vars) set to "" or whitespace only.

Common situations: Exporting ASTRID_SESSION_ID= empty in a shell profile; a wrapper script exporting the var before assigning it; CI templates with an unfilled placeholder.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• --var has an invalid key (got {key:?})
• secret value for {key} exceeds 65536-byte limit
• environment value for {key} exceeds 1048576-byte limit
• invalid value for {}.{}: expected one of {}, got {value:?}
• MCP attach host is empty

AI-assisted analysis of astrid-runtime/astrid@affd8760f4 (2026-09-09). Data as JSON: /api/errors/0b656705c399be96. Report an issue: GitHub.