{"record":{"id":"081f7eb51284f006","repo":"astrid-runtime/astrid","slug":"unsupported-mcp-gateway-control-version","errorCode":null,"errorMessage":"unsupported MCP gateway control version {}","messagePattern":"unsupported MCP gateway control version (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/astrid-cli/src/commands/mcp/gateway.rs","lineNumber":905,"sourceCode":"        let byte = reader\n            .read_u8()\n            .await\n            .context(\"failed to read MCP attach registration\")?;\n        if byte == b'\\n' {\n            terminated = true;\n            break;\n        }\n        line.push(byte);\n    }\n    if !terminated {\n        anyhow::bail!(\"MCP attach registration is missing or too large\");\n    }\n    let request: GatewayRequest =\n        serde_json::from_slice(&line).context(\"MCP gateway registration is not valid JSON\")?;\n    match &request {\n        GatewayRequest::Control(control) => {\n            if control.version != GATEWAY_CONTROL_VERSION {\n                anyhow::bail!(\n                    \"unsupported MCP gateway control version {}\",\n                    control.version\n                );\n            }\n            if control.pid == 0 || control.hook_token.trim().is_empty() {\n                anyhow::bail!(\"MCP gateway control authority is incomplete\");\n            }\n        },\n        GatewayRequest::Attach(registration) => validate_registration(registration)?,\n    }\n    Ok(request)\n}\n\nfn validate_registration(registration: &AttachRegistration) -> Result<()> {\n    if registration.version != ATTACH_REGISTRATION_VERSION {\n        anyhow::bail!(\n            \"unsupported MCP attach registration version {}\",\n            registration.version","sourceCodeStart":887,"sourceCodeEnd":923,"githubUrl":"https://github.com/astrid-runtime/astrid/blob/affd8760f44190dbdfbec23403f4c4b642c33112/crates/astrid-cli/src/commands/mcp/gateway.rs#L887-L923","documentation":"Control requests on the gateway socket carry a protocol version field that must equal GATEWAY_CONTROL_VERSION. When a client sends a GatewayRequest::Control whose version differs, read_gateway_request_inner rejects it. This guards the control channel against clients speaking an incompatible protocol revision.","triggerScenarios":"Sending a control request (stop/status) with control.version != GATEWAY_CONTROL_VERSION from read_gateway_request/read_registration_inner parsing.","commonSituations":"Mixed-version CLI and daemon after an upgrade (old astrid binary talking to a newer gateway or vice versa); hand-crafted control scripts with a hardcoded version number; a stale daemon running old code.","solutions":["Upgrade or downgrade so the client and gateway come from the same build; check `astrid --version` on both sides.","Restart/kill any stale gateway daemon left from a previous version so a fresh one with matching GATEWAY_CONTROL_VERSION starts.","Update custom control scripts to use the current GATEWAY_CONTROL_VERSION constant from the codebase.","Clear stale socket/lease files under daemon_root before reconnecting so the old-version gateway is not reused."],"exampleFix":"// before: custom script pins an old version\n{\"type\":\"control\",\"version\":0,\"pid\":1234,\"hook_token\":\"...\"}\n// after: use the constant the library exports\nlet req = json!({\"type\":\"control\",\"version\":GATEWAY_CONTROL_VERSION,\"pid\":std::process::id(),\"hook_token\":token});","handlingStrategy":"validation","validationCode":"fn control_version_ok(v: u32, expected: u32) -> bool { v == expected }","typeGuard":null,"tryCatchPattern":"match result {\n    Err(e) if e.to_string().contains(\"unsupported MCP gateway control version\") => eprintln!(\"client/gateway version skew: restart the gateway and match versions\"),\n    other => other?,\n}","preventionTips":["Ship client and gateway from the same build.","Reference GATEWAY_CONTROL_VERSION instead of hardcoding numbers.","Restart stale daemons after upgrades.","Check versions on both ends before opening the control channel."],"tags":["mcp","versioning","protocol","gateway"],"backgroundTag":"unsupported-enum-value","analyzedSha":"affd8760f44190dbdfbec23403f4c4b642c33112","analyzedAt":"2026-09-09T21:28:12.402Z","contentChangedAt":"2026-09-09T21:28:12.402Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}