{
  "id": "dotnet/grpc-ssl-handshake-failed",
  "signature": "Grpc.Core.RpcException: Status(StatusCode=\"Unavailable\", Detail=\"failed to connect to all addresses; last error: UNKNOWN: Failed SSL handshake\")",
  "signature_zh": "Grpc.Core.RpcException: Status(StatusCode=\"Unavailable\", Detail=\"无法连接到所有地址；最后一个错误：UNKNOWN: SSL 握手失败\")",
  "regex": "Failed SSL handshake|StatusCode=\"Unavailable\"",
  "domain": "dotnet",
  "category": "network_error",
  "subcategory": null,
  "root_cause": "gRPC client fails SSL/TLS handshake with server due to mismatched protocols, missing or invalid certificates, or server not supporting HTTP/2 over TLS.",
  "root_cause_type": "generic",
  "root_cause_zh": "gRPC 客户端因协议不匹配、证书缺失或无效、或服务器不支持基于 TLS 的 HTTP/2 而导致 SSL/TLS 握手失败。",
  "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": "Grpc.Net.Client 2.49",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Grpc.Net.Client 2.52",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "Disable SSL validation entirely by setting ServicePointManager.ServerCertificateValidationCallback = delegate { return true; }",
      "why_fails": "Disabling SSL validation creates a severe security vulnerability and may not fix protocol-level mismatches like TLS version or cipher suite.",
      "fail_rate": 0.9,
      "condition": "",
      "sources": []
    },
    {
      "action": "Use HTTP/1.1 instead of HTTP/2",
      "why_fails": "gRPC requires HTTP/2; switching to HTTP/1.1 will cause protocol errors and the gRPC call will fail with a different error.",
      "fail_rate": 0.95,
      "condition": "",
      "sources": []
    },
    {
      "action": "Set AppContext switch to ignore certificate revocation",
      "why_fails": "Ignoring revocation does not address root cause of handshake failure (e.g., mismatched cipher suites or expired certificate).",
      "fail_rate": 0.85,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Ensure server certificate is trusted by client machine. Install the server's CA certificate using certmgr.msc or update Linux CA store.",
      "success_rate": 0.85,
      "how": "Ensure server certificate is trusted by client machine. Install the server's CA certificate using certmgr.msc or update Linux CA store.",
      "condition": "",
      "sources": []
    },
    {
      "action": "Configure gRPC client to use specific TLS version: AppContext.SetSwitch(\"System.Net.Http.SocketsHttpHandler.Http2UnencryptedSupport\", false); and set HttpClientHandler.SslProtocols = SslProtocols.Tls12;",
      "success_rate": 0.8,
      "how": "Configure gRPC client to use specific TLS version: AppContext.SetSwitch(\"System.Net.Http.SocketsHttpHandler.Http2UnencryptedSupport\", false); and set HttpClientHandler.SslProtocols = SslProtocols.Tls12;",
      "condition": "",
      "sources": []
    },
    {
      "action": "If using .NET Core 3.1+ and server uses self-signed cert, add client code: var handler = new HttpClientHandler(); handler.ServerCertificateCustomValidationCallback = HttpClientHandler.DangerousAcceptAnyServerCertificateValidator; (not for production).",
      "success_rate": 0.95,
      "how": "If using .NET Core 3.1+ and server uses self-signed cert, add client code: var handler = new HttpClientHandler(); handler.ServerCertificateCustomValidationCallback = HttpClientHandler.DangerousAcceptAnyServerCertificateValidator; (not for production).",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "确保服务器证书被客户端信任。使用 certmgr.msc 或更新 Linux CA 存储安装服务器的 CA 证书。",
    "配置 gRPC 客户端使用特定 TLS 版本：AppContext.SetSwitch(\"System.Net.Http.SocketsHttpHandler.Http2UnencryptedSupport\", false); 并设置 HttpClientHandler.SslProtocols = SslProtocols.Tls12;",
    "如果使用 .NET Core 3.1+ 且服务器使用自签名证书，添加客户端代码：var handler = new HttpClientHandler(); handler.ServerCertificateCustomValidationCallback = HttpClientHandler.DangerousAcceptAnyServerCertificateValidator;（不适用于生产环境）。"
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://learn.microsoft.com/en-us/aspnet/core/grpc/troubleshoot",
  "official_doc_section": null,
  "error_code": null,
  "verification_tier": "ai_generated",
  "confidence": 0.87,
  "fix_success_rate": 0.82,
  "resolvable": "true",
  "first_seen": "2023-02-15",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}