Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

nginx refuses to start: host not found in upstream

Errornginx: [emerg] host not found in upstream

Short 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.

  • Applies to nginx 1.26, nginx 1.28
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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.internal
  2. 2Match what you see, then jump to its fix

    1. 1The message names the host from a proxy_pass lineThe host name in proxy_pass has no address when nginx loads itFix
    2. 2The message names a host from a server line inside an upstream blockThe upstream group lists a host name that cannot be resolvedFix

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.internal

2Fix

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

Did this fix it?

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.com

2Fix

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 reload

Confirmed by nginx.org

Did this fix it?

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

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.