astrid-runtime/astrid · error

unsupported MCP attach registration version {}

Error message

unsupported MCP attach registration version {}

What it means

validate_registration checks that an incoming GatewayRequest::Attach registration's version equals ATTACH_REGISTRATION_VERSION before resolving the principal or examining any other fields. A mismatched version is rejected immediately so older/newer clients cannot attach with an incompatible registration schema.

Source

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

        GatewayRequest::Control(control) => {
            if control.version != GATEWAY_CONTROL_VERSION {
                anyhow::bail!(
                    "unsupported MCP gateway control version {}",
                    control.version
                );
            }
            if control.pid == 0 || control.hook_token.trim().is_empty() {
                anyhow::bail!("MCP gateway control authority is incomplete");
            }
        },
        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(())
}

View on GitHub (pinned to affd8760f4)

Solutions

1. Align versions: upgrade or reinstall astrid on both the attaching client and the daemon/gateway host so ATTACH_REGISTRATION_VERSION matches.
2. Update custom integrations to serialize registration.version from the current constant instead of a literal.
3. Restart the gateway daemon after upgrades so it is not running stale code from a previous socket lease.
4. Clear stale gateway ready/lease/socket files under daemon_root before reconnecting post-upgrade.

Example fix

// before
AttachRegistration { version: 1, host, host_session_id, principal, hook_token }
// after
AttachRegistration { version: ATTACH_REGISTRATION_VERSION, host, host_session_id, principal, hook_token }

fn registration_version_ok(v: u32, expected: u32) -> bool { v == expected }

match result {
    Err(e) if e.to_string().contains("unsupported MCP attach registration version") => eprintln!("upgrade client and gateway to the same version"),
    other => other?,
}

When it happens

Trigger: An attach client sends a registration whose registration.version differs from the gateway's ATTACH_REGISTRATION_VERSION constant; called from read_gateway_request_inner during preface parsing.

Common situations: Version skew after upgrading the CLI on one side only (editor extension old, CLI new, or vice versa); a custom attach client hardcoding a stale version; replaying a recorded/cached registration payload from an older protocol revision.

Related errors

• unsupported MCP gateway control version {}
• durable capsule {id} has unsupported authority schema {}
• MCP gateway attach limit reached for principal '{principal}'
• {primary:#}; additional gateway cleanup failure: {secondary:
• expected MCP attach registration

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