NGINX & Docker error: Host not found in upstream

Understanding the NGINX Docker Upstream Error

When using NGINX as a reverse proxy in a Docker environment, you might occasionally encounter the error message ‘Host not found in upstream’. This error signifies that NGINX is unable to resolve the service name provided in the upstream configuration to a network address.

Common Causes

• Service-specific network not being accessible to the NGINX container.
• Typos or misconfiguration in the NGINX configuration file.
• DNS resolution issues within the Docker network.
• Timing problems where the dependent service may not be up and running before NGINX starts.

Possible Solutions to Fix the Error

Solution 1: Correct Service Names

Ensure all referenced service names in your NGINX configuration match exactly with those defined in your docker-compose.yml or Docker service commands.

Steps:

1. Open the NGINX configuration file (nginx.conf).
2. Compare the service names listed in the upstream block with those defined in Docker.
3. Correct any discrepancies by updating the configuration to have the exact names.
4. Reload NGINX to apply changes.

Example:

upstream myapp_server {
    server web:80;
}

Note: Make sure ‘web’ is the service name used in Docker to describe the container hosting the application.

Solution 2: Check for DNS Resolution Issues

Verify if the Docker internal DNS is able to resolve the service names by connecting to the NGINX container and using the ping command.

Steps:

1. Execute docker exec -it nginx_container_name /bin/sh to connect to your NGINX container.
2. Within the NGINX container, try pinging the service: ping web.
3. If the ping is unsuccessful, investigate the DNS settings or service definitions in Docker.

This solution only requires verifying the operational state rather than changing configuration files.

Solution 3: Delay NGINX Startup

Configure the start-up sequence of your Docker containers so that NGINX does not try to resolve services before they are available.

Steps:

1. Define dependencies in your docker-compose.yml using the depends_on option.
2. Consider using a wait-for-it script for NGINX to delay its start until the required service is up.

Example:

services:
  web:
    image: myapp

  nginx:
    image: nginx
    depends_on:
      - web

In this configuration:

• You have defined two services: web and nginx.
• The web service uses an image named myapp.
• The nginx service uses the nginx image and is set to depend on the web service, meaning nginx will only start after the web service has been started.

Summary

Addressing the ‘Host not found in upstream’ error involves verifying the service names, checking DNS resolution within Docker, and making sure that services have started up in the correct order. By following the provided solutions, you should be able to resolve the error and have a working NGINX reverse proxy setup in your Docker environment.