nginx refuses to start: host not found in upstream
nginx: [emerg] host not found in upstreamShort answer
The message means nginx could not turn the host name in your proxy_pass or upstream server line into an IP address. Check that the name resolves from this machine. If the address changes, give nginx a resolver and use a variable in proxy_pass, or the resolve parameter in an upstream group.
Fix it fast
1Find out which cause you have
Find the host name nginx is complaining about, then ask the system resolver for it from the same machine.
sudo nginx -t getent hosts backend.internal2Match what you see, then jump to its fix
What does the error look like?
nginx: [emerg] host not found in upstream
Cause 1 of 2
The host name in proxy_pass has no address when nginx loads it
1Check
getent returns nothing for the name, or the name is not registered in DNS yet because the service behind it has not started. The message appears when nginx has no address for that name.
grep -R -n "proxy_pass" /etc/nginx/
getent hosts backend.internal2Fix
Put the name in a variable and give nginx a resolver. With a variable, nginx looks the name up through the resolver instead, and answers are cached by their TTL. Note that with a variable and a URI in proxy_pass, the URI replaces the original request URI.
resolver 10.0.0.2 valid=30s;
location / {
set $backend http://backend.internal:3000;
proxy_pass $backend;
}3Verify
Test and reload. A request should reach the app, even if it was down when nginx started.
sudo nginx -t && sudo nginx -s reload
curl -I http://localhost/Confirmed by nginx.org
Cause 2 of 2
The upstream group lists a host name that cannot be resolved
1Check
In an upstream group a host name is converted into one or more addresses, and a name with several addresses becomes several servers. A name that does not resolve leaves nothing to put into the group.
grep -R -n -A4 "upstream " /etc/nginx/
getent hosts backend3.example.com2Fix
Use the resolve parameter so nginx keeps watching the name and updates the group without a restart. It needs a shared memory zone and a resolver. Before nginx 1.27.3 this parameter was only in the commercial subscription.
resolver 10.0.0.2;
upstream app {
zone app 64k;
server backend3.example.com resolve;
}3Verify
Test the config and reload.
sudo nginx -t && sudo nginx -s reloadConfirmed by nginx.org
How do I stop it coming back?
- Use IP addresses in upstream blocks when the target never moves.
- Set the resolver to a name server your host really reaches, and set valid= so answers refresh at a rate you choose.
- Run getent hosts for every upstream name before you reload.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
Related fixes
Servers
Angular routes return 404 from nginx when you refresh or open a link
The home page loads, but refreshing /some/route shows an nginx 404
Angular routes like /users/42 are not files, so nginx looks for them on disk and returns 404.
3 causes, each with a fixServers
Argo CD behind an nginx Ingress loops with too many redirects
307 Temporary Redirect on every request to the Argo CD host
The browser and Argo CD disagree about who handles TLS.
3 causes, each with a fixServers
A Let's Encrypt certificate did not renew with Certbot
Type: connection ... Timeout during connect (likely firewall problem)
Run sudo certbot renew --dry-run and read the Type and Detail lines.
6 causes, each with a fixServers
curl cannot connect to port 80 or 443 on a server running nginx
CURLE_COULDNT_CONNECT (7): Failed to connect() to host or proxy
Exit code 7 means the TCP connection itself failed, before any HTTP happened.
3 causes, each with a fixServers
Django returns a 500 behind Gunicorn and the traceback is nowhere
The traceback shows locally with runserver but not under Gunicorn
With DEBUG set to False, Django's default logging does not print errors to the console.
2 causes, each with a fixServers
Docker php image has no php.ini and my edits do not stay
A setting changed in php.ini inside the container is gone after the container is recreated
The official php image ships php.ini-development and php.ini-production but no active php.ini.
2 causes, each with a fix