Nginx-proxy ignores server context when Docker labels are malformed, missing required environment variables like
VIRTUAL_HOST, or when the proxy container lacks network access to upstream services. This guide provides step-by-step instructions to diagnose label syntax errors, verify network connectivity, and ensure correct configuration generation in a Docker environment.
Understanding Nginx-Proxy Label Requirements
The core mechanism of
jwilder/nginx-proxy relies entirely on Docker labels attached to the target containers. If the proxy seems to ignore your server context, the most common culprit is an incorrect or missing label. The proxy scans running containers for specific metadata to generate its dynamic configuration files. Without these labels, the container is invisible to the proxy manager.
You must ensure that every service intended to be proxied has the
VIRTUAL_HOST label defined. This label specifies the domain name that will route traffic to the container. For example, if you want your application accessible at
example.com, the label must be set precisely as
VIRTUAL_HOST=example.com. Note that wildcards like
*.example.com are also supported, but the syntax must be exact. Missing this label is the primary reason why contexts appear ignored.
Additionally, check for the
VIRTUAL_PORT label. If your application runs on a non-standard port (not 80), you must specify it. Without this, the proxy attempts to connect to port 80 by default, which may result in connection refused errors or silent failures depending on the upstream service. Always verify that the port specified matches the actual listening port inside the container.
Verifying Docker Network Connectivity
Even with perfect labels, the proxy cannot reach your application if they are not on the same Docker network. By default, new containers join the
bridge network, but custom setups often use isolated networks for security or organization. If your nginx-proxy container and your web application container are on different networks, the proxy cannot resolve the container names via DNS.
To fix this, explicitly attach both containers to the same user-defined bridge network. You can do this during creation using the
--network flag or by defining a shared network in your
docker-compose.yml file. Ensure that the network name is consistent across all relevant services.
Test connectivity by executing a command inside the nginx-proxy container. Use
docker exec -it ping . If the ping fails, the network isolation is the issue. Reconfigure your compose file to include a shared network definition. This ensures that internal DNS resolution works correctly, allowing the proxy to forward requests to the correct upstream IP addresses.
For more details on managing complex Docker environments, see
Coolify Environment: Docker Compose PHP Web Server with Nginx Proxy and Gettng Gateway Timeout.
Debugging Configuration Generation
When the proxy appears to ignore context, inspecting the generated configuration files is crucial. The nginx-proxy container dynamically generates
/etc/nginx/conf.d/default.conf based on the labels it detects. If this file does not contain your server block, the proxy has not seen your container's labels.
Access the proxy container and view the configuration file. Look for a
server block matching your
VIRTUAL_HOST value. If it is missing, the proxy failed to read the labels. This often happens due to permission issues or race conditions where the proxy starts before the application container is fully labeled. Restarting the proxy container after the application is up can sometimes resolve transient synchronization issues.
Check the logs of the nginx-proxy container using
docker logs . Look for warnings about invalid labels or network errors. Common log messages include "invalid label" or "cannot connect to upstream." These messages provide direct clues about what is failing. If the logs show successful detection but the config is wrong, there may be a syntax error in the label values.
Common Label Syntax Errors
Syntax errors in labels are subtle and hard to spot. A single typo in the label key can prevent detection. Ensure that the label key is exactly
com.github.jrcs.vhost or simply
VIRTUAL_HOST depending on your version. Older versions might require different keys, but modern setups standardize on
VIRTUAL_HOST.
Another frequent error involves trailing slashes or extra spaces in the domain name.
VIRTUAL_HOST=example.com with a trailing space is treated as a different host than
VIRTUAL_HOST=example.com. Always trim whitespace in your docker-compose files. Use quotes around values to prevent shell interpretation issues.
Also, verify that you are not conflicting with other reverse proxy tools. If you have multiple proxies running, they might interfere with each other's label scanning. Disable any other active proxy instances to isolate the problem.
See
SSL Certificates Not Generated with Certbot for Nginx in Docker for related issues involving SSL and label configurations.
Frequently Asked Questions
Why is my nginx-proxy returning 502 Bad Gateway?
This usually indicates that the proxy can reach the server but cannot establish a valid HTTP connection to the upstream application. Check that the
VIRTUAL_PORT label matches the port your app is actually listening on. Ensure the app container is healthy and responding to HTTP requests directly.
How do I debug missing VIRTUAL_HOST labels?
Run
docker inspect and look under the
Config.Labels section. Verify that
VIRTUAL_HOST exists and contains a valid domain string. If it is missing, add it to your docker-compose configuration and restart the container.
Can I use multiple domains with one container?
Yes, you can separate domain names with commas in the
VIRTUAL_HOST label. For example,
VIRTUAL_HOST=example.com,www.example.com. The proxy will create a single server block that listens for both domains.
What if the proxy container doesn't start?
Check the container logs for initialization errors. Ensure the proxy has read/write access to the Docker socket. It requires mounting
/var/run/docker.sock to monitor container events. Without this mount, it cannot detect new containers or label changes.
Does nginx-proxy support IPv6?
Standard nginx-proxy primarily supports IPv4. If you need IPv6 support, you may need to configure additional parameters or use a modified version of the image. Check the official documentation for specific IPv6 label extensions or workarounds.