How to Debug an Nginx Server Block
This guide walks you through debugging an Nginx server block, which is the configuration block that tells Nginx how to handle requests for a specific domain or IP. You’ll learn how to identify syntax errors, configuration logic issues, and runtime problems, and how to fix them step by step. Before starting, you need root or sudo access to your server and a basic understanding of the command line.
What You’ll Need
- A server running Nginx (any recent version, e.g., 1.18+).
- SSH access with sudo privileges.
- Knowledge of the path to your server block file (commonly /etc/nginx/sites-available/ or /etc/nginx/conf.d/).
- A text editor (nano, vim, or similar).
- Optional: a web browser and curl for testing.
Step-by-Step
- Identify the server block file. List your Nginx configuration directories:
ls /etc/nginx/sites-available/orls /etc/nginx/conf.d/. The server block you’re debugging is usually named after your domain (e.g., example.com). If you’re not sure which file is active, check the main nginx.conf forincludedirectives. - Test the configuration syntax. Run
sudo nginx -t. This checks all configuration files for syntax errors. If there’s a problem, it will tell you the exact file and line number. Fix any errors before proceeding. - Check for duplicate server names. If you have multiple server blocks for the same domain, Nginx may use the first one it encounters. Run
sudo nginx -T(capital T) to dump the full configuration. Look for duplicateserver_namedirectives. Remove or comment out duplicates. - Verify the server_name matches. In your server block, ensure the
server_namematches the domain you’re testing. Usecurl -H "Host: yourdomain.com" http://localhostto simulate a request. If you get the wrong response, your server_name is likely wrong or missing. - Check listen directives. Make sure the
listendirective specifies the correct port (80 for HTTP, 443 for HTTPS) and IP. If you’re using HTTPS, confirm the SSL certificate paths are correct and the files exist. Runsudo ls -l /path/to/cert.pemto verify. - Test with curl. Use
curl -I http://yourdomain.com(or https) to see the response headers. A 200 OK means the server block is working. A 404 or 403 might indicate a root or index issue. A 301/302 might mean a redirect is happening unexpectedly. - Check the error log. Nginx logs errors to /var/log/nginx/error.log by default. Run
sudo tail -f /var/log/nginx/error.login one terminal, then make a request in another. Look for messages like “no server_name” or “directory index is forbidden”. - Verify the root and index. Ensure the
rootdirective points to an existing directory, and that theindexdirective lists a file that exists (e.g., index.html). Test withsudo ls /var/www/html. - Check for conflicting location blocks. If you have multiple
locationblocks, Nginx uses the longest prefix match (or regex in order). Review your location blocks for overlapping patterns. For example, a location / and location /api/ might conflict if not ordered correctly. - Reload Nginx after changes. After any edit, run
sudo nginx -tagain, thensudo systemctl reload nginx(orsudo service nginx reload). Reloading applies changes without dropping connections. - Test with a browser. Clear your browser cache or use incognito mode. Visit your domain. If it still fails, use the browser’s developer tools (F12) to check the Network tab for status codes and response headers.
- Check firewall and DNS. If the server block seems correct but the site is unreachable, verify that your firewall allows traffic on ports 80/443 (e.g.,
sudo ufw status). Also confirm that your domain’s DNS points to your server’s IP.
Common Mistakes
- Missing semicolons. Every directive in Nginx ends with a semicolon. Forgetting one causes a syntax error.
- Wrong file permissions. Nginx worker processes need read access to the root directory and files. If permissions are too restrictive, you get a 403 Forbidden.
- Using relative paths. Always use absolute paths in root and include directives.
- Forgetting to reload. After editing a config file, you must reload Nginx. A common mistake is editing but not reloading, so the old config stays active.
- Duplicate server blocks. Having two server blocks with the same server_name can cause unpredictable behavior. Nginx uses the first one found, which may not be the one you expect.
- Incorrect SSL certificate paths. For HTTPS, a typo in the certificate path will prevent Nginx from starting.
Tips
- Use nginx -T to see the full config. This shows how all includes are resolved, making it easier to spot duplicates or missing parts.
- Comment out suspicious lines. If you’re not sure which directive causes an issue, comment it out with #, test, and reload. This helps isolate the problem.
- Keep a backup. Before making changes, copy the original file:
sudo cp /etc/nginx/sites-available/yourdomain /etc/nginx/sites-available/yourdomain.bak. - Use curl to test locally. Curl gives you more control than a browser and shows raw headers. Use
curl -vfor verbose output. - Check the access log too. /var/log/nginx/access.log shows request details, which can help you see if requests are reaching the server block at all.
Troubleshooting
If the steps above don’t resolve the issue, try these additional approaches:
- If nginx -t fails: The error message tells you the file and line. Open that file, fix the syntax, and re-test. If the error mentions a missing file or directory, create it or correct the path.
- If Nginx won’t start: Check the system log:
sudo journalctl -u nginx(on systemd systems). Common causes are syntax errors or missing SSL files. Fix them and trysudo systemctl start nginx. - If you get a 404: The server block is being used, but the root or index is wrong. Check the root path and ensure the index file exists. Also check for try_files directives that might be misconfigured.
- If you get a 403: Permissions issue. Ensure the root directory has execute permission for others (e.g.,
sudo chmod 755 /var/www/html) and files are readable (644). - If you get a redirect loop: This often happens with HTTPS redirects. Check your server block for a rewrite or return 301 that points to itself. Make sure the redirect URL uses the correct scheme.
- If the site works but with the wrong content: Your server_name might be too broad (e.g., a wildcard like *.example.com catching everything). Use a more specific server_name or add a default server block.
Frequently Asked Questions
Why does nginx -t say “test failed” but I can’t see an error?
Run sudo nginx -t with more verbosity: sudo nginx -t -c /etc/nginx/nginx.conf. Sometimes the error is in an included file. Check the main nginx.conf for include lines and test each included file separately.
My changes aren’t taking effect even after reload.
Make sure you’re editing the correct file that is actually included. Use sudo nginx -T to see which file is active. Also, check if there’s a symlink in sites-enabled pointing to your file. If not, create one: sudo ln -s /etc/nginx/sites-available/yourdomain /etc/nginx/sites-enabled/.
How do I debug a 502 Bad Gateway error?
This means Nginx can’t reach your upstream (e.g., a PHP-FPM or Node.js process). Check that the upstream service is running, and verify the proxy_pass or fastcgi_pass directive in your server block points to the correct socket or port.
Can I test a server block without affecting the live site?
Yes, you can use a different port. Change the listen directive to a test port (e.g., 8080) and access it via http://yourdomain.com:8080. Just remember to revert it after testing.
Why does my server block work for www but not the bare domain?
You likely have two server blocks: one for www and one for the bare domain. If the bare domain block lacks a server_name or has a typo, it won’t match. Also, check for a default server block that might be catching it.
How do I see which server block is handling a request?
Add a custom header to each server block temporarily, like add_header X-Server "test1";, then reload and use curl -I to see which header appears. This is a quick way to identify the active block.
Related
Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.