The file on disk can differ from nginx’s running configuration. An unapplied edit does not affect traffic; a syntactically valid edit can still route requests incorrectly. Check both syntax and behavior.
Find the relevant server and location
nginx -T validates configuration and prints the files it reads, including includes. Match listen, server_name, location and upstream or static paths to the specific URL. The output may contain sensitive settings.
sudo nginx -Troot appends the request URI; alias replaces the matching location prefix. For static-file failures, compare the resulting path with the actual file.
Validate before reloading
After a small edit, run nginx -t. On failure, read the filename and line number, correct the issue and test again. A successful test does not check backend availability or JavaScript execution in a browser.
sudo nginx -tnginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successfulMessages and paths depend on the build. The important result is a successful exit status.
Reload and repeat the same request
nginx -s reload asks the master to reread configuration. New workers accept new connections while old workers finish existing ones. Check error.log and reproduce the original request with the same Host.
sudo nginx -t && sudo nginx -s reload
curl -sS -i --max-time 5 -H 'Host: shop.example.test' http://127.0.0.1/If behavior is wrong, compare expectations with logs and revert the specific edit if needed. Avoid changing several unrelated settings at once.
Separate proxying from static delivery
For 502, inspect the upstream address and application reachability. For a blank 200 page, inspect HTML, asset URLs and Content-Type. nginx -t helps avoid syntax errors in both, but the causes live in different configuration paths.
Change one hypothesis at a time: retain the prior fragment, adjust the relevant location or path, validate and apply. Comparing the same URL before and after is more informative than rebuilding every server block together.
A configuration that parses successfully may still contain the wrong upstream, root or alias.
From symptom to check
| Observation | Next check | How to interpret it |
|---|---|---|
| nginx -t failed | Reported file and line | First repair the configuration-validation failure. |
| nginx -t succeeds, HTTP 502 | proxy_pass and direct backend | Syntax is valid, but the address or application may be wrong. |
| JavaScript receives the wrong MIME type | location, alias/root and file | Verify the actual resource instead of disabling browser checks. |
Common mistakes
- Rebooting the server instead of a small validated reload.
- Deleting an include without understanding its role.
- Treating a file’s existence as proof it is served at the intended URL.
How to prove recovery
- Confirm nginx -t succeeds before applying.
- Check reload and fresh master/worker errors.
- Use the same URL and Host before and after.
- For static assets verify the browser; for proxying verify the backend business request.
MINI INCIDENT
The file exists, but the browser will not execute it
A new JavaScript file exists, HTML references an old name, and /assets/ points at a prior release. Why is a Content-Type change alone insufficient?
HTML: /assets/app-old.js
files: /srv/www/assets/app-new.js
location: /srv/previous-release/assets/Explore the diagnosis
Align the reference, served path and content type, then verify the response and interface. A MIME header neither creates a missing file nor changes the URL in HTML.
WORKSHOP
Workshop: explain the evidence and choose an action
Syntax validation succeeds, but an asset path reaches the wrong handler.
GET /assets/bundle.js → 200 text/html
GET /api/orders → 200 application/json
nginx -t → successfulWhy is “nginx works” too broad?
Compare your reasoning
Different paths can use different locations and backends. API success does not test static delivery, and valid syntax does not establish URL-to-file correctness.
What should be inspected in effective configuration?
Compare your reasoning
Inspect the Host-selected server, location rules, root/alias, fallback and MIME mapping. Relate them to the exact URL and its path within the chosen location.
Which sequence supports the repair?
Compare your reasoning
Validate syntax, apply configuration and GET the exact resource while checking body and type. For JavaScript, then load the browser page because curl does not execute the application.
CHECK YOUR UNDERSTANDING
nginx -t passed. Does that prove the site works?
Show explanation
No. It validates configuration rather than the user journey. After reloading, verify the response, page resources and the required browser action.
No comments yet. Share your first impression or ask a question about this topic.