{
  "id": "go/grpc-tls-handshake-failure",
  "signature": "rpc error: code = Unavailable desc = connection error: desc = \"transport: authentication handshake failed: tls: failed to verify certificate: x509: certificate signed by unknown authority\"",
  "signature_zh": "rpc 错误：code = Unavailable desc = 连接错误：\"传输层：认证握手失败：tls: 无法验证证书：x509: 证书由未知机构签名\"",
  "regex": "rpc\\ error:\\ code\\ =\\ Unavailable\\ desc\\ =\\ connection\\ error:\\ desc\\ =\\ \"transport:\\ authentication\\ handshake\\ failed:\\ tls:\\ failed\\ to\\ verify\\ certificate:\\ x509:\\ certificate\\ signed\\ by\\ unknown\\ authority\"",
  "domain": "go",
  "category": "auth_error",
  "subcategory": null,
  "root_cause": "The client's root CA pool does not contain the CA that signed the server certificate. Common with self-signed certs, internal CAs, or missing grpc.WithTransportCredentials.",
  "root_cause_type": "generic",
  "root_cause_zh": "客户端的根 CA 池不包含签发服务器证书的 CA。常见于自签名证书、内部 CA，或缺少 grpc.WithTransportCredentials。",
  "versions": [
    {
      "version": "1.50+",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "",
      "why_fails": "Disables certificate validation entirely, exposing the connection to MITM. Not acceptable in production.",
      "fail_rate": 0.9,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "Mismatches the server's TLS listener; the handshake fails with a different error (record layer failure).",
      "fail_rate": 0.85,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "",
      "success_rate": 0.93,
      "how": "b, _ := os.ReadFile(\"ca.pem\")\ncp := x509.NewCertPool()\ncp.AppendCertsFromPEM(b)\ncreds := credentials.NewTLS(&tls.Config{RootCAs: cp, ServerName: \"myservice.internal\"})\nconn, err := grpc.Dial(addr, grpc.WithTransportCredentials(creds))",
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "success_rate": 0.85,
      "how": "creds := credentials.NewTLS(&tls.Config{})\n// or explicitly:\n// tls.Config{RootCAs: nil} uses the host's system pool",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": null,
  "official_doc_section": null,
  "error_code": null,
  "verification_tier": "ai_generated",
  "confidence": 0.9,
  "fix_success_rate": 0.8,
  "resolvable": "true",
  "first_seen": "2024-08-11",
  "last_confirmed": "2025-01-01",
  "last_updated": "2025-01-01",
  "evidence_count": 0,
  "tags": [],
  "locale": "en",
  "aliases": []
}