Deploy on Vexlo Cloud in 60s (₹149/mo UPI) — India's First & Only Developer PaaS. Instant INR UPI & 17 global currencies ($5/mo).
Deploy Now
Bucket 1: Docker & Node.js Fatal Errors6 min readVerified

Fixing nginx: [emerg] host not found in upstream Using Docker DNS Resolver 127.0.0.11

Solve nginx: [emerg] host not found in upstream in Docker Compose and Swarm. Configure Docker's internal DNS resolver 127.0.0.11 with dynamic set $upstream variables so Nginx boots and survives container restarts.

TL;DR — Immediate Production Fix

By default, Nginx resolves every hostname written inside an `upstream {}` block or a static `proxy_pass http://app:3000;` directive ONCE at startup using the system `/etc/resolv.conf`, and permanently caches that IP address for the lifetime of the master process. If the `app` container is not running yet when Nginx boots, Nginx crashes immediately with `nginx: [emerg] host not found in upstream`. Furthermore, if `app` is recreated later with a new Docker bridge IP, Nginx continues routing to the dead IP (returning 502 Bad Gateway). Fix both issues permanently by adding `resolver 127.0.0.11 valid=10s ipv6=off;` and assigning the upstream hostname to a runtime Nginx variable (`set $upstream http://app:3000; proxy_pass $upstream;`).

Verified Root Causes in Production Environments

  • Static Boot-Time DNS Resolution in Nginx Open Source: Literal hostnames in `proxy_pass http://web:3000` or `upstream backend { server web:3000; }` are resolved synchronously during configuration parsing before worker processes even start.
  • Stale Container IP Caching After Redeployments: Even if `depends_on` lets Nginx start after `web`, running `docker compose up -d --build web` assigns a brand-new `172.18.0.x` IP to `web`, while Nginx keeps forwarding traffic to the old container IP.
  • Default Bridge Network Lacks Embedded DNS: Using the legacy default `bridge` network instead of a user-defined Docker Compose network disables the `127.0.0.11` internal DNS server.

1. How Docker's Embedded DNS Server (127.0.0.11) Works With Nginx Variables

Every container attached to a user-defined Docker Compose network has `/etc/resolv.conf` pointed to `nameserver 127.0.0.11`, which is the Docker daemon's built-in service discovery DNS resolver. However, Nginx Open Source only queries a custom `resolver` directive dynamically at request time when the target hostname inside `proxy_pass` contains an Nginx variable (such as `$upstream_app`).

When you replace a hardcoded `proxy_pass http://nextjs-app:3000;` with `resolver 127.0.0.11 valid=10s ipv6=off;` followed by `set $upstream_app http://nextjs-app:3000; proxy_pass $upstream_app;`, two critical behaviours change: (1) Nginx no longer checks if `nextjs-app` exists in DNS at startup, so the Nginx container boots cleanly even if the backend container is down, and (2) Nginx re-queries `127.0.0.11` every 10 seconds (`valid=10s`), automatically picking up new container IP addresses during rolling redeployments.

nginx/conf.d/default.conf
nginx
server {
    listen 80;
    server_name vexlo.cloud www.vexlo.cloud;

    # 1. Declare Docker's internal embedded DNS server (127.0.0.11)
    # valid=10s forces Nginx to refresh container IPs every 10 seconds after redeploys
    resolver 127.0.0.11 valid=10s ipv6=off;
    resolver_timeout 5s;

    location / {
        # 2. Store the upstream service name in a variable to force runtime DNS lookup
        set $backend_upstream "http://nextjs-app:3000";
        proxy_pass $backend_upstream;

        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

2. Critical Gotcha: URI Path Stripping When Using Variables in proxy_pass

There is a subtle Nginx URI-rewriting rule that trips up senior engineers when switching `proxy_pass` from a static string to a variable. In standard Nginx, writing `location /api/ { proxy_pass http://backend:4000/; }` strips the `/api/` prefix before forwarding the request. However, when `proxy_pass` uses a variable (`proxy_pass $api_upstream;`), Nginx passes the full original `$request_uri` unchanged unless you explicitly capture and append the regex path inside the variable.

Below is the exact pattern for both root proxying (preserving `$request_uri`) and prefix-stripping sub-path proxying (`/api/v1/*` forwarded as `/*`) using `127.0.0.11`.

nginx/conf.d/subpath-rewrite.conf
nginx
server {
    listen 80;
    resolver 127.0.0.11 valid=10s ipv6=off;

    # Pattern A: Pass full URI unchanged to upstream
    location / {
        set $web_upstream "http://frontend:3000";
        proxy_pass $web_upstream;
    }

    # Pattern B: Strip '/api/' prefix when using a variable in proxy_pass
    location ~ ^/api/(.*)$ {
        set $api_upstream "http://api-service:4000";
        # Explicitly append captured group $1 and query args $is_args$args
        proxy_pass $api_upstream/$1$is_args$args;
        proxy_set_header Host $host;
    }
}

3. Complete Docker Compose Configuration With Shared Bridge Network

Remember that `127.0.0.11` is only injected into containers that use a Docker Compose network (either the default network created by `docker compose up` or an explicit custom network). If you launch containers manually via `docker run` without `--network`, `127.0.0.11` will not exist. Always declare an explicit bridge network in `docker-compose.yml`.

docker-compose.yml
yaml
services:
  nginx:
    image: nginx:1.27-alpine
    restart: always
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx/conf.d:/etc/nginx/conf.d:ro
    networks:
      - app-net

  nextjs-app:
    build: .
    restart: unless-stopped
    expose:
      - "3000"
    networks:
      - app-net

networks:
  app-net:
    driver: bridge

Pre-Deployment Verification Checklist

  • Add resolver 127.0.0.11 valid=10s ipv6=off; inside your Nginx server {} or http {} block.
  • Replace static proxy_pass http://service:port; with set $upstream http://service:port; proxy_pass $upstream;.
  • Remove static upstream {} blocks that reference container names unless using nginx:1.27.3+ with the resolve parameter.
  • Verify both Nginx and your upstream container are attached to the same Docker Compose bridge network.
India's First & Only Developer PaaS

Deploy on Vexlo Cloud in 60s (₹149/mo UPI)

Automated Docker & Nixpacks builds, managed PostgreSQL/Redis, and AI Deployment Doctor. Instant INR UPI for India or USD/EUR/GBP across 17 global currencies.

Frequently Asked Questions

Why does Nginx still return 502 Bad Gateway after I restart my Node.js container?

When you recreate or restart a container, Docker assigns it a new internal IP (e.g., changing from 172.18.0.3 to 172.18.0.5). Without `resolver 127.0.0.11 valid=10s` and a `$variable` in `proxy_pass`, Nginx caches 172.18.0.3 forever until you reload Nginx.

Can I use the resolve keyword inside an upstream {} block in free Nginx Open Source?

Historically, `server app:3000 resolve;` inside an `upstream` block was exclusive to Nginx Plus, though Nginx Open Source 1.27.3+ recently added native `resolve` support in `upstream` blocks (requiring `resolver 127.0.0.11;` and `zone`). The `set $upstream` variable method works universally across all Nginx versions.

Why should I include ipv6=off in the Docker Nginx resolver directive?

Standard Docker bridge networks are IPv4-only by default. Without `ipv6=off`, Nginx attempts AAAA IPv6 lookups alongside A lookups, causing unnecessary DNS latency and log warnings.

Primary Upstream References & Specifications

Keep Debugging

Related Guides

Browse all 30 guides →