Lesson 4 of 10Diagnostics

12 min · theory and practice · Basics

nginx: validate and reload configuration

Check syntax, effective configuration and behavior after a reload.

You will be able to make one change and verify that it actually took effect.

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.

Commands
sudo nginx -T

root 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.

Commands
sudo nginx -t
Example output
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

Messages 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.

Commands
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

ObservationNext checkHow to interpret it
nginx -t failedReported file and lineFirst repair the configuration-validation failure.
nginx -t succeeds, HTTP 502proxy_pass and direct backendSyntax is valid, but the address or application may be wrong.
JavaScript receives the wrong MIME typelocation, alias/root and fileVerify 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

  1. Confirm nginx -t succeeds before applying.
  2. Check reload and fresh master/worker errors.
  3. Use the same URL and Host before and after.
  4. 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?

Evidence to investigate
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.

Sample evidence
GET /assets/bundle.js → 200 text/html
GET /api/orders       → 200 application/json
nginx -t              → successful
  1. Why 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.

  2. 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.

  3. 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.

Documentation

Guest progress is stored separately in this browser.

TAKE IT TO THE TERMINAL

Practice on an incident

Use configuration checks in the nginx case or investigate static delivery in the blank-page case.

DID IT MAKE SENSE?

Was this article helpful?

Rate the article or tell us what needed more explanation. Your feedback helps improve the lessons.

Helpful 0 Not helpful 0

Sign in to rate this article and leave a comment.

Discussion

0

Join the discussion →

No comments yet. Share your first impression or ask a question about this topic.