{
  "id": "go/grpc-tls-handshake-failed",
  "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 = 连接错误：desc = \"transport：认证握手失败：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 gRPC client connected with TLS but the server's certificate chain is not trusted by the client's root CA pool.",
  "root_cause_type": "generic",
  "root_cause_zh": "gRPC 客户端使用 TLS 连接，但服务端证书链不被客户端的根 CA 池信任。",
  "versions": [
    {
      "version": "google.golang.org/grpc 1.0+",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "",
      "why_fails": "Disables all certificate validation, exposing the client to MITM; not acceptable in production.",
      "fail_rate": 0.6,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "Certificate trust is deterministic; retries fail identically.",
      "fail_rate": 0.95,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "",
      "success_rate": 0.95,
      "how": "Load the correct CA into the client's root pool:\ncertPool := x509.NewCertPool()\npem, _ := os.ReadFile(\"ca.pem\")\ncertPool.AppendCertsFromPEM(pem)\ncreds := credentials.NewTLS(&tls.Config{RootCAs: certPool})\nconn, _ := grpc.NewClient(addr, grpc.WithTransportCredentials(creds))",
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "success_rate": 0.9,
      "how": "For internal/self-signed setups, use mTLS with a shared CA:\ncreds := credentials.NewTLS(&tls.Config{\n    Certificates: []tls.Certificate{clientCert},\n    RootCAs:      certPool,\n    ServerName:   \"api.internal\",\n})",
      "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.89,
  "fix_success_rate": 0.8,
  "resolvable": "true",
  "first_seen": "2024-01-15",
  "last_confirmed": "2025-01-01",
  "last_updated": "2025-01-01",
  "evidence_count": 0,
  "tags": [],
  "locale": "en",
  "aliases": []
}