{
  "id": "grpc/ssl-target-name-override-mismatch",
  "signature": "UNAVAILABLE: SSL target name override mismatch: expected 'service.example.com' but got 'backend.internal'",
  "signature_zh": "UNAVAILABLE: SSL目标名称覆盖不匹配：期望'service.example.com'但收到'backend.internal'",
  "regex": "UNAVAILABLE: SSL target name override mismatch: expected '\\S+' but got '\\S+'",
  "domain": "grpc",
  "category": "tls_error",
  "subcategory": null,
  "root_cause": "gRPC client SSL/TLS target name override (via 'grpc.ssl_target_name_override') doesn't match the server's TLS certificate Common Name (CN) or Subject Alternative Name (SAN), causing handshake failure.",
  "root_cause_type": "generic",
  "root_cause_zh": "gRPC客户端SSL/TLS目标名称覆盖（通过'grpc.ssl_target_name_override'）与服务器TLS证书的通用名称（CN）或主题备用名称（SAN）不匹配，导致握手失败。",
  "versions": [
    {
      "version": "gRPC v1.61.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "gRPC-Go v1.63.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "OpenSSL 1.1.1w",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "",
      "why_fails": "Disabling SSL verification entirely ('grpc.ssl_target_name_override='') exposes the connection to man-in-the-middle attacks and may not resolve if the server enforces TLS.",
      "fail_rate": 0.8,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "Changing the server's hostname in the client target URL without updating the override value causes a different mismatch; the error persists if the override still points to the old name.",
      "fail_rate": 0.85,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "Regenerating the server certificate with the same mismatched name doesn't fix the client-side override; the client must be updated to match the new certificate name.",
      "fail_rate": 0.9,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Update the client's SSL target name override: set 'grpc.ssl_target_name_override' to the exact CN/SAN in the server certificate (e.g., 'backend.internal'); in Python: 'grpc.secure_channel(target, credentials, options=[(\"grpc.ssl_target_name_override\", \"backend.internal\")])'.",
      "success_rate": 0.95,
      "how": "Update the client's SSL target name override: set 'grpc.ssl_target_name_override' to the exact CN/SAN in the server certificate (e.g., 'backend.internal'); in Python: 'grpc.secure_channel(target, credentials, options=[(\"grpc.ssl_target_name_override\", \"backend.internal\")])'.",
      "condition": "",
      "sources": []
    },
    {
      "action": "Regenerate the server TLS certificate with the correct SAN: include both 'service.example.com' and 'backend.internal' in the Subject Alternative Names to match the client override; restart the server to load the new certificate.",
      "success_rate": 0.85,
      "how": "Regenerate the server TLS certificate with the correct SAN: include both 'service.example.com' and 'backend.internal' in the Subject Alternative Names to match the client override; restart the server to load the new certificate.",
      "condition": "",
      "sources": []
    },
    {
      "action": "Remove the override entirely: if the client target URL matches the certificate's CN/SAN, omit 'grpc.ssl_target_name_override' to use automatic hostname verification; ensure DNS resolves correctly.",
      "success_rate": 0.9,
      "how": "Remove the override entirely: if the client target URL matches the certificate's CN/SAN, omit 'grpc.ssl_target_name_override' to use automatic hostname verification; ensure DNS resolves correctly.",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "更新客户端的SSL目标名称覆盖：将'grpc.ssl_target_name_override'设置为服务器证书中的确切CN/SAN（如'backend.internal'）；在Python中：'grpc.secure_channel(target, credentials, options=[(\"grpc.ssl_target_name_override\", \"backend.internal\")])'。",
    "使用正确的SAN重新生成服务器TLS证书：在主题备用名称中包含'service.example.com'和'backend.internal'以匹配客户端覆盖；重启服务器以加载新证书。",
    "完全移除覆盖：如果客户端目标URL与证书的CN/SAN匹配，省略'grpc.ssl_target_name_override'以使用自动主机名验证；确保DNS正确解析。"
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://grpc.io/docs/guides/auth/#ssl-tls",
  "official_doc_section": null,
  "error_code": null,
  "verification_tier": "ai_generated",
  "confidence": 0.86,
  "fix_success_rate": 0.87,
  "resolvable": "true",
  "first_seen": "2024-05-08",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}