{"record":{"id":"143da2c3c7f3c6da","repo":"Hmbown/CodeWhale","slug":"mcp-configuration-changed-reload-it-before-retrying-this","errorCode":null,"errorMessage":"MCP configuration changed; reload it before retrying this server","messagePattern":"MCP configuration changed; reload it before retrying this server","errorType":"http","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"crates/tui/src/runtime_api.rs","lineNumber":4683,"sourceCode":"/// return the actual result without replacing healthy sibling connections.\nasync fn reconnect_mcp_server(\n    State(state): State<RuntimeApiState>,\n    Path(name): Path<String>,\n) -> Result<Json<McpServerActionReceipt>, ApiError> {\n    let (config, _) = mcp_management_config(&state)?;\n    if !config.servers.contains_key(&name) {\n        return Err(ApiError::not_found(format!(\n            \"MCP server '{name}' not found\"\n        )));\n    }\n    let handle = mcp_pool_handle(&state, true)\n        .await?\n        .ok_or_else(|| ApiError::internal(\"MCP pool unavailable\"))?;\n    let mut pool = handle.lock().await;\n    let error = if !config.servers[&name].is_enabled() {\n        Some(anyhow::anyhow!(\"MCP server '{name}' is disabled\"))\n    } else if !pool.config_matches(&config) {\n        Some(anyhow::anyhow!(\n            \"MCP configuration changed; reload it before retrying this server\"\n        ))\n    } else {\n        pool.retry_connection(&name).await.err()\n    };\n    let connection = mcp_connection_outcome(&pool, &name, error.as_ref());\n    Ok(Json(McpServerActionReceipt {\n        revision: None,\n        name,\n        action: if error.is_none() {\n            \"reconnected\"\n        } else {\n            \"reconnect_failed\"\n        },\n        ok: error.is_none() && connection.connected,\n        connection: Some(connection),\n    }))\n}","sourceCodeStart":4665,"sourceCodeEnd":4701,"githubUrl":"https://github.com/Hmbown/CodeWhale/blob/73e0f67d83c59909b571efdfc88c4bc28c309cb1/crates/tui/src/runtime_api.rs#L4665-L4701","documentation":"The retry endpoint checks pool.config_matches(&config) after the enabled check. If the fresh config differs from the pool's snapshot, retry is refused and this error is recorded as the outcome, mirroring the connect endpoint's stale-pool guard but phrased for retries.","triggerScenarios":"Calling the MCP retry endpoint while the MCP configuration has been edited since the pool was loaded, so config_matches returns false; the per-server name in the request is enabled but the pool is stale.","commonSituations":"Adding a new server or changing env/args in the MCP config and immediately hitting retry without reload; CI or automation rewriting mcp config between calls.","solutions":["Reload the MCP configuration via the Runtime API reload endpoint (or restart the Runtime API), then retry the server.","Diff the on-disk MCP config against the pool's snapshot to identify what changed unintentionally.","Sequence automation: config edit -> reload -> retry, never config edit -> retry."],"exampleFix":"// before\nPOST /mcp/retry {\"server\": \"github\"}  // -> stale config error\n\n// after\nPOST /mcp/reload\nPOST /mcp/retry {\"server\": \"github\"}","handlingStrategy":"retry","validationCode":"let pool_hash = fetch_pool_config_hash().await?;\nif pool_hash != hash_of(&fetch_mcp_config().await?) {\n    call_mcp_reload().await?;\n}","typeGuard":null,"tryCatchPattern":"match outcome.error {\n    Some(e) if e.contains(\"configuration changed\") => {\n        client.reload_mcp_config().await?;\n        client.mcp_retry(name).await?;\n    }\n    other => handle(other),\n}","preventionTips":["Reload MCP config immediately after edits, before any retry","Serialize config edits through a single automation step that reloads","Verify server state via the listing endpoint before retry loops"],"tags":["mcp","runtime-api","stale-state"],"backgroundTag":"invalid-state-transition","analyzedSha":"73e0f67d83c59909b571efdfc88c4bc28c309cb1","analyzedAt":"2026-09-22T01:30:00.501Z","contentChangedAt":"2026-09-22T01:30:00.501Z","schemaVersion":2},"datasetVersion":"2026-09-22T21:17:16.096Z"}