# 不可用: grpc: Envoy UDS 连接失败: /tmp/envoy.sock

- **ID:** `grpc/grpc-envoy-uds-connection-failed`
- **领域:** grpc
- **类别:** network_error
- **验证级别:** ai_generated
- **修复率:** 85%

## 根因

gRPC 客户端无法通过 Unix Domain Socket 连接到 Envoy，原因是套接字文件缺失、权限问题或 Envoy 未监听。

## 版本兼容性

| 版本 | 状态 | 引入 | 弃用 |
|------|------|------|------|
| envoy 1.29.0 | active | — | — |
| grpc-go 1.63.0 | active | — | — |
| grpc-python 1.61.0 | active | — | — |
| Istio 1.20.0 | active | — | — |

## 解决方案

1. ```
   Verify the UDS socket exists and has correct permissions. Run:
  ls -la /tmp/envoy.sock
  If missing, check Envoy logs for startup errors: envoy -c envoy.yaml --log-level debug
  Ensure the socket path in Envoy config matches the client path. Example Envoy config:
  listeners:
  - name: grpc_listener
    address:
      pipe:
        path: /tmp/envoy.sock
    filter_chains:
    - filters:
      - name: envoy.filters.network.http_connection_manager
        typed_config: ...
   ```
2. ```
   If permissions are wrong, change them:
  sudo chmod 777 /tmp/envoy.sock
  Or run Envoy with the same user as the gRPC client to avoid permission issues.
   ```

## 无效尝试

- **** — Envoy is configured to listen on a specific socket path; changing client path without updating Envoy causes mismatch. (90% 失败率)
- **** — This bypasses UDS but may introduce network overhead and requires Envoy to be configured for TCP as well. (75% 失败率)