{
  "id": "grpc/grpc-envoy-uds-connection-failed",
  "signature": "UNAVAILABLE: grpc: Envoy UDS connection failed: /tmp/envoy.sock",
  "signature_zh": "不可用: grpc: Envoy UDS 连接失败: /tmp/envoy.sock",
  "regex": "UNAVAILABLE: grpc: Envoy UDS connection failed: /tmp/envoy\\.sock",
  "domain": "grpc",
  "category": "network_error",
  "subcategory": null,
  "root_cause": "gRPC client cannot connect to Envoy via Unix Domain Socket due to socket file missing, permissions issues, or Envoy not listening.",
  "root_cause_type": "generic",
  "root_cause_zh": "gRPC 客户端无法通过 Unix Domain Socket 连接到 Envoy，原因是套接字文件缺失、权限问题或 Envoy 未监听。",
  "versions": [
    {
      "version": "envoy 1.29.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "grpc-go 1.63.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "grpc-python 1.61.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Istio 1.20.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "",
      "why_fails": "Envoy is configured to listen on a specific socket path; changing client path without updating Envoy causes mismatch.",
      "fail_rate": 0.9,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "This bypasses UDS but may introduce network overhead and requires Envoy to be configured for TCP as well.",
      "fail_rate": 0.75,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Verify the UDS socket exists and has correct permissions. Run:\n  ls -la /tmp/envoy.sock\n  If missing, check Envoy logs for startup errors: envoy -c envoy.yaml --log-level debug\n  Ensure the socket path in Envoy config matches the client path. Example Envoy config:\n  listeners:\n  - name: grpc_listener\n    address:\n      pipe:\n        path: /tmp/envoy.sock\n    filter_chains:\n    - filters:\n      - name: envoy.filters.network.http_connection_manager\n        typed_config: ...",
      "success_rate": 0.9,
      "how": "Verify the UDS socket exists and has correct permissions. Run:\n  ls -la /tmp/envoy.sock\n  If missing, check Envoy logs for startup errors: envoy -c envoy.yaml --log-level debug\n  Ensure the socket path in Envoy config matches the client path. Example Envoy config:\n  listeners:\n  - name: grpc_listener\n    address:\n      pipe:\n        path: /tmp/envoy.sock\n    filter_chains:\n    - filters:\n      - name: envoy.filters.network.http_connection_manager\n        typed_config: ...",
      "condition": "",
      "sources": []
    },
    {
      "action": "If permissions are wrong, change them:\n  sudo chmod 777 /tmp/envoy.sock\n  Or run Envoy with the same user as the gRPC client to avoid permission issues.",
      "success_rate": 0.8,
      "how": "If permissions are wrong, change them:\n  sudo chmod 777 /tmp/envoy.sock\n  Or run Envoy with the same user as the gRPC client to avoid permission issues.",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "Verify the UDS socket exists and has correct permissions. Run:\n  ls -la /tmp/envoy.sock\n  If missing, check Envoy logs for startup errors: envoy -c envoy.yaml --log-level debug\n  Ensure the socket path in Envoy config matches the client path. Example Envoy config:\n  listeners:\n  - name: grpc_listener\n    address:\n      pipe:\n        path: /tmp/envoy.sock\n    filter_chains:\n    - filters:\n      - name: envoy.filters.network.http_connection_manager\n        typed_config: ...",
    "If permissions are wrong, change them:\n  sudo chmod 777 /tmp/envoy.sock\n  Or run Envoy with the same user as the gRPC client to avoid permission issues."
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://www.envoyproxy.io/docs/envoy/latest/configuration/listeners/listeners",
  "official_doc_section": null,
  "error_code": null,
  "verification_tier": "ai_generated",
  "confidence": 0.88,
  "fix_success_rate": 0.85,
  "resolvable": "true",
  "first_seen": "2024-04-01",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}