# gRPC error: UNAVAILABLE. DNS resolution failed for service: my-service.example.com:443

- **ID:** `api/grpc-unavailable-dns-resolution`
- **Domain:** api
- **Category:** network_error
- **Error Code:** `UNAVAILABLE`
- **Verification:** ai_generated
- **Fix Rate:** 80%

## Root Cause

gRPC client cannot resolve the target service hostname due to DNS configuration issues or network connectivity problems.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| gRPC v1.56.0 | active | — | — |
| Envoy proxy 1.27 | active | — | — |
| Kubernetes 1.28 | active | — | — |

## Workarounds

1. **Verify DNS resolution manually: run 'dig my-service.example.com' or 'nslookup my-service.example.com'. If it fails, check /etc/resolv.conf for valid nameservers (e.g., 8.8.8.8).** (85% success)
   ```
   Verify DNS resolution manually: run 'dig my-service.example.com' or 'nslookup my-service.example.com'. If it fails, check /etc/resolv.conf for valid nameservers (e.g., 8.8.8.8).
   ```
2. **Increase gRPC DNS resolver timeout: set GRPC_DNS_RESOLVER_TIMEOUT_MS=5000 environment variable before starting the client.** (70% success)
   ```
   Increase gRPC DNS resolver timeout: set GRPC_DNS_RESOLVER_TIMEOUT_MS=5000 environment variable before starting the client.
   ```
3. **If using Kubernetes, ensure the service DNS name matches the gRPC target (e.g., my-service.namespace.svc.cluster.local). Use 'kubectl run -it --rm debug --image=busybox -- nslookup my-service' to test.** (80% success)
   ```
   If using Kubernetes, ensure the service DNS name matches the gRPC target (e.g., my-service.namespace.svc.cluster.local). Use 'kubectl run -it --rm debug --image=busybox -- nslookup my-service' to test.
   ```

## Dead Ends

- **** — Restarting the gRPC client without fixing DNS configuration (e.g., missing /etc/resolv.conf entries) will reproduce the same error. (75% fail)
- **** — Changing the target endpoint to an IP address bypasses DNS but may fail if the service uses virtual hosting or TLS SNI requires the hostname. (60% fail)