# upstream DNS resolution timed out

- **ID:** `nginx/upstream-dns-resolution-timed-out`
- **Domain:** nginx
- **Category:** network_error
- **Verification:** ai_generated
- **Fix Rate:** 88%

## Root Cause

Nginx cannot resolve the upstream hostname because the resolver is not configured, the DNS server is unreachable, or the hostname is invalid.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| nginx 1.18.0 | active | — | — |
| nginx 1.20.2 | active | — | — |
| nginx 1.22.1 | active | — | — |
| nginx 1.24.0 | active | — | — |
| nginx 1.25.3 | active | — | — |

## Workarounds

1. **Configure a valid resolver in the http block: resolver 10.0.0.53 valid=10s; (replace with your DNS server IP)** (90% success)
   ```
   Configure a valid resolver in the http block: resolver 10.0.0.53 valid=10s; (replace with your DNS server IP)
   ```
2. **If using Docker, set dns: in docker-compose.yml or add --dns flag to docker run** (85% success)
   ```
   If using Docker, set dns: in docker-compose.yml or add --dns flag to docker run
   ```
3. **Check /etc/resolv.conf and ensure nginx has network access to the DNS server** (80% success)
   ```
   Check /etc/resolv.conf and ensure nginx has network access to the DNS server
   ```

## Dead Ends

- **** — If the server has no outbound internet access, public DNS won't work; need internal DNS. (60% fail)
- **** — This bypasses DNS but makes the config brittle if IPs change; not a proper fix. (40% fail)
- **** — If DNS is unreachable, timeout increase just delays the error. (80% fail)