{
  "id": "dotnet/signalr-negotiate-version",
  "signature": "Microsoft.AspNetCore.SignalR.HubException: Failed to negotiate with the server. The server returned an unsupported negotiate version.",
  "signature_zh": "Microsoft.AspNetCore.SignalR.HubException: 与服务器协商失败。服务器返回了不支持的协商版本。",
  "regex": "Failed to negotiate with the server\\. The server returned an unsupported negotiate version",
  "domain": "dotnet",
  "category": "protocol_error",
  "subcategory": null,
  "root_cause": "SignalR client and server negotiate connection parameters; an unsupported negotiate version error occurs when the client uses an outdated or incompatible SignalR protocol version that the server does not recognize.",
  "root_cause_type": "generic",
  "root_cause_zh": "SignalR 客户端和服务器协商连接参数；当客户端使用的 SignalR 协议版本过时或不兼容，服务器无法识别时，会出现不支持的协商版本错误。",
  "versions": [
    {
      "version": ".NET 6.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": ".NET 7.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": ".NET 8.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Microsoft.AspNetCore.SignalR.Client 6.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Microsoft.AspNetCore.SignalR.Client 7.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Microsoft.AspNetCore.SignalR.Client 8.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "Set HubConnectionBuilder to use raw WebSockets without negotiation",
      "why_fails": "Disabling negotiation may bypass version check but causes connection failures if the server requires negotiation for transports like Server-Sent Events.",
      "fail_rate": 0.8,
      "condition": "",
      "sources": []
    },
    {
      "action": "Upgrade only the client-side SignalR package to the latest version",
      "why_fails": "If the server is an older version, the latest client may introduce a negotiate version the server doesn't support; both sides must be compatible.",
      "fail_rate": 0.65,
      "condition": "",
      "sources": []
    },
    {
      "action": "Ignore the error and retry connection with exponential backoff",
      "why_fails": "Retrying does not fix the protocol version mismatch; the negotiate request will fail repeatedly.",
      "fail_rate": 0.95,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Ensure both client and server use the same major version of Microsoft.AspNetCore.SignalR (e.g., both 6.0.x or both 8.0.x). Check .csproj files and server packages.",
      "success_rate": 0.9,
      "how": "Ensure both client and server use the same major version of Microsoft.AspNetCore.SignalR (e.g., both 6.0.x or both 8.0.x). Check .csproj files and server packages.",
      "condition": "",
      "sources": []
    },
    {
      "action": "If using a custom negotiation endpoint, update it to return the correct negotiate response with protocol version 1 or higher.",
      "success_rate": 0.85,
      "how": "If using a custom negotiation endpoint, update it to return the correct negotiate response with protocol version 1 or higher.",
      "condition": "",
      "sources": []
    },
    {
      "action": "Downgrade the client package to match the server version: dotnet add package Microsoft.AspNetCore.SignalR.Client --version 6.0.25",
      "success_rate": 0.88,
      "how": "Downgrade the client package to match the server version: dotnet add package Microsoft.AspNetCore.SignalR.Client --version 6.0.25",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "确保客户端和服务器使用相同主版本的 Microsoft.AspNetCore.SignalR（例如均为 6.0.x 或 8.0.x）。检查 .csproj 文件和服务器包。",
    "如果使用自定义协商端点，更新它以返回包含协议版本 1 或更高版本的正确协商响应。",
    "降级客户端包以匹配服务器版本：dotnet add package Microsoft.AspNetCore.SignalR.Client --version 6.0.25"
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://learn.microsoft.com/en-us/aspnet/core/signalr/troubleshoot",
  "official_doc_section": null,
  "error_code": null,
  "verification_tier": "ai_generated",
  "confidence": 0.84,
  "fix_success_rate": 0.88,
  "resolvable": "true",
  "first_seen": "2023-09-05",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}