# UNAVAILABLE: SSL target name override mismatch: expected 'service.example.com' but got 'backend.internal'

- **ID:** `grpc/ssl-target-name-override-mismatch`
- **Domain:** grpc
- **Category:** tls_error
- **Verification:** ai_generated
- **Fix Rate:** 87%

## Root Cause

gRPC client SSL/TLS target name override (via 'grpc.ssl_target_name_override') doesn't match the server's TLS certificate Common Name (CN) or Subject Alternative Name (SAN), causing handshake failure.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| gRPC v1.61.0 | active | — | — |
| gRPC-Go v1.63.0 | active | — | — |
| OpenSSL 1.1.1w | active | — | — |

## Workarounds

1. **Update the client's SSL target name override: set 'grpc.ssl_target_name_override' to the exact CN/SAN in the server certificate (e.g., 'backend.internal'); in Python: 'grpc.secure_channel(target, credentials, options=[("grpc.ssl_target_name_override", "backend.internal")])'.** (95% success)
   ```
   Update the client's SSL target name override: set 'grpc.ssl_target_name_override' to the exact CN/SAN in the server certificate (e.g., 'backend.internal'); in Python: 'grpc.secure_channel(target, credentials, options=[("grpc.ssl_target_name_override", "backend.internal")])'.
   ```
2. **Regenerate the server TLS certificate with the correct SAN: include both 'service.example.com' and 'backend.internal' in the Subject Alternative Names to match the client override; restart the server to load the new certificate.** (85% success)
   ```
   Regenerate the server TLS certificate with the correct SAN: include both 'service.example.com' and 'backend.internal' in the Subject Alternative Names to match the client override; restart the server to load the new certificate.
   ```
3. **Remove the override entirely: if the client target URL matches the certificate's CN/SAN, omit 'grpc.ssl_target_name_override' to use automatic hostname verification; ensure DNS resolves correctly.** (90% success)
   ```
   Remove the override entirely: if the client target URL matches the certificate's CN/SAN, omit 'grpc.ssl_target_name_override' to use automatic hostname verification; ensure DNS resolves correctly.
   ```

## Dead Ends

- **** — Disabling SSL verification entirely ('grpc.ssl_target_name_override='') exposes the connection to man-in-the-middle attacks and may not resolve if the server enforces TLS. (80% fail)
- **** — Changing the server's hostname in the client target URL without updating the override value causes a different mismatch; the error persists if the override still points to the old name. (85% fail)
- **** — Regenerating the server certificate with the same mismatched name doesn't fix the client-side override; the client must be updated to match the new certificate name. (90% fail)