astrid-runtime/astrid · error

MCP attach registration has an empty host_session_id

Error message

MCP attach registration has an empty host_session_id

What it means

validate_registration checks that an MCP attach registration payload carries all required identity fields before the gateway accepts it. The host_session_id identifies which gateway session the attach request belongs to; when it is absent or whitespace-only, the gateway cannot correlate the request and bails immediately. This is a fail-fast guard on the wire protocol.

Source

Thrown at crates/astrid-cli/src/commands/mcp/gateway.rs:931

        },
        GatewayRequest::Attach(registration) => validate_registration(registration)?,
    }
    Ok(request)
}

fn validate_registration(registration: &AttachRegistration) -> Result<()> {
    if registration.version != ATTACH_REGISTRATION_VERSION {
        anyhow::bail!(
            "unsupported MCP attach registration version {}",
            registration.version
        );
    }
    super::lifecycle::resolve_principal(Some(&registration.principal))?;
    if registration.host.trim().is_empty() {
        anyhow::bail!("MCP attach registration has an empty host");
    }
    if registration.host_session_id.trim().is_empty() {
        anyhow::bail!("MCP attach registration has an empty host_session_id");
    }
    if registration.hook_token.trim().is_empty() {
        anyhow::bail!("MCP attach registration is missing hook_token");
    }
    validate_workspace(&registration.workspace_abs)?;
    Ok(())
}

fn authenticate_registration(
    registration: &AttachRegistration,
    state: &GatewayState,
) -> Result<astrid_core::PrincipalId> {
    let principal = super::lifecycle::resolve_principal(Some(&registration.principal))?;
    if principal != state.principal {
        anyhow::bail!(
            "MCP attach registration principal '{}' is not the authenticated gateway principal '{}'",
            principal,
            state.principal

View on GitHub (pinned to affd8760f4)

Solutions

1. Set host_session_id to the gateway session identifier returned by the gateway startup/lifecycle flow before sending the attach request
2. If hand-building the payload, add the host_session_id field explicitly
3. Check client version compatibility — older clients may not populate host_session_id; upgrade or add it to the payload
4. Trim/verify the value on the client side before submitting

Example fix

// before
let registration = AttachRegistration { host: "127.0.0.1:0".into(), host_session_id: "".into(), .. };
// after
let registration = AttachRegistration { host: "127.0.0.1:0".into(), host_session_id: lease.boot_token.clone(), .. };

fn ensure_registration(reg: &AttachRegistration) -> Result<(), String> {
    if reg.host_session_id.trim().is_empty() { return Err("host_session_id is required".into()); }
    Ok(())
}

fn has_host_session_id(reg: &AttachRegistration) -> bool { !reg.host_session_id.trim().is_empty() }

When it happens

Trigger: Calling the MCP attach flow (read_gateway_request_inner -> validate_registration) with a serialized AttachRegistration whose host_session_id field is missing, empty, or contains only whitespace.

Common situations: A hand-written JSON registration payload omitting host_session_id; a client library or older client version that doesn't send the field; template/config placeholders left unfilled (""); env interpolation producing whitespace.

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

• MCP attach host session key is empty
• MCP attach host is empty
• MCP gateway control authority is incomplete
• MCP attach registration has an empty host
• MCP attach registration is missing hook_token

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