Demo Troubleshooting

And welcome to the final demo.

A clean presentation slide showing the word "Troubleshooting" on the left and a large turquoise shape on the right labeled "Demo." A small "© Copyright KodeKloud" appears in the bottom-left.

This guide collects practical troubleshooting steps for NGINX: quick checks, common configuration mistakes, and safe commands to apply changes in production. Follow the sequence below to diagnose most NGINX issues quickly and safely.

Quick checks (first steps)

Is the NGINX process running? sudo systemctl status nginx
Has configuration syntax changed? nginx -t
Are the expected ports open (80/443) locally and externally?
Are site logs present and owned by the web user?

Use the checklist at the end to confirm you didn’t miss any step.

Always test configuration first: nginx -t

Run nginx -t after editing configuration. It validates syntax and reports errors so you don’t break the running service on reload. Example: missing semicolon leads to an error

root@nginx:~# nginx -t
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
root@nginx:~# vim /etc/nginx/sites-available/example-https
# make a typo (missing semicolon) and save
root@nginx:~# nginx -t
nginx: [emerg] directive "deny" is not terminated by ";" in /etc/nginx/sites-enabled/example-https:9
nginx: configuration file /etc/nginx/nginx.conf test failed

Common causes of nginx -t failures:

Syntax errors (missing ; or mismatched braces).
Directives placed in the wrong context (see next section).
Missing files referenced by the config (certificates, include files).

Context errors: directives must be in the right block

Some directives are only valid in specific contexts (main, http, server, location). Putting an http { ... } block inside a server block will fail. Example error when a directive is not allowed in this context

root@nginx:~# nginx -t
nginx: [emerg] "http" directive is not allowed here in /etc/nginx/sites-enabled/example-https:33
nginx: configuration file /etc/nginx/nginx.conf test failed

Correct usage: http is a top-level context in /etc/nginx/nginx.conf; server and location are nested inside it. Common bad snippet that triggers errors (do not put http inside server):

server {
    listen 80;
    server_name example.com;
    return 301 https://$host$request_uri;

    http {
        access_log /var/log/nginx/access.log;  # WRONG: http block is not allowed here
    }
}

Apply changes gracefully: reload vs restart

Prefer reloading the configuration so worker processes are replaced without dropping connections.

Reload (graceful): nginx -s reload or sudo systemctl reload nginx
Restart (full stop/start): sudo systemctl restart nginx

Avoid restart unless necessary. restart interrupts active connections briefly; reload applies configuration changes without downtime when nginx -t reports OK.

Always run nginx -t and then nginx -s reload (or systemctl reload nginx) if the test is successful. Use restart only for recovering failed workers or replacing the master process.

Main configuration and logging

The global configuration file /etc/nginx/nginx.conf contains the http block and global logging settings. When hosting multiple sites, configure per-site logs to simplify debugging. Example of key sections in /etc/nginx/nginx.conf:

user www-data;
worker_processes auto;
pid /run/nginx.pid;
include /etc/nginx/modules-enabled/*.conf;

events {
    worker_connections 768;
}

http {
    ##
    # Basic Settings
    ##
    sendfile on;
    tcp_nopush on;
    types_hash_max_size 2048;
    include /etc/nginx/mime.types;
    default_type application/octet-stream;

    ##
    # SSL Settings
    ##
    ssl_protocols TLSv1.2 TLSv1.3; # prefer modern TLS
    ssl_prefer_server_ciphers on;

    ##
    # Logging Settings
    ##
    access_log /var/log/nginx/access.log;
    error_log /var/log/nginx/error.log;

    ##
    # Gzip Settings
    ##
    gzip on;

    ##
    # Virtual Host Configs
    ##
    include /etc/nginx/conf.d/*.conf;
    include /etc/nginx/sites-enabled/*;
}

Note: It’s safer to leave defaults (like worker_processes) unless you understand the performance implications.

Per-site logging (recommended)

Configure each virtual host to write to its own log directory. Create the directory before reloading NGINX — NGINX will create files but not parent directories. Example server block for a site with per-site logs:

server {
    listen 80;
    server_name example.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name example.com;

    ssl_certificate /etc/ssl/certs/example.com.pem;
    ssl_certificate_key /etc/ssl/certs/example.com-key.pem;

    root /var/www/html;

    access_log /var/log/nginx/example.com/access.log;
    error_log  /var/log/nginx/example.com/error.log;

    add_header Strict-Transport-Security "max-age=31560000; includeSubDomains; preload";
    add_header X-Frame-Options "SAMEORIGIN";
    add_header Content-Security-Policy "default-src 'self'";
    add_header Referrer-Policy origin;

    index index.html index.htm index.nginx-debian.html;

    location / {
        try_files $uri $uri/ =404;
    }
}

Create log directory and set ownership

# create the directory (if not present)
sudo mkdir -p /var/log/nginx/example.com
# verify configuration syntax
sudo nginx -t
# set sensible ownership and permissions
sudo chown -R www-data:adm /var/log/nginx/example.com
# reload nginx to apply changes
sudo nginx -s reload
# inspect logs
ls -l /var/log/nginx/example.com
tail -f /var/log/nginx/example.com/access.log

Verify reachability with curl

Use curl from the server to check whether NGINX serves requests. This distinguishes between NGINX, DNS, and firewall issues. Examples:

# quick check to see server response (full body)
curl localhost

# get only headers to check status code quickly
curl --head https://example.com
# or
curl -I https://example.com

If NGINX is stopped, curl will fail — indicating the service is the problem:

sudo systemctl stop nginx
curl --head https://example.com
# curl will hang/fail because there's no webserver responding

Hosts file for local resolution

For testing or when the server needs to resolve its own hostname, add entries to /etc/hosts. Example:

127.0.0.1 localhost example.com www.example.com
# On some distributions (e.g., Debian) you may also see a separate line like:
# IPv6 entries
::1 ip6-localhost ip6-loopback

Firewalls and cloud provider security

Confirm both the server firewall (UFW, firewalld) and any cloud security groups (AWS Security Groups, GCP firewall rules, etc.) allow required ports (80 and 443). Example ufw status output:

Status: active

To                         Action      From
--                         -------     ----
22/tcp                     ALLOW       Anywhere
80/tcp                     ALLOW       Anywhere
443/tcp                    ALLOW       Anywhere
22/tcp (v6)                ALLOW       Anywhere (v6)
80/tcp (v6)                ALLOW       Anywhere (v6)
443/tcp (v6)               ALLOW       Anywhere (v6)

Why port 80 still matters

Even if your site redirects HTTP to HTTPS, leaving port 80 closed prevents users visiting http://example.com from being redirected. Best practice: keep both 80 and 443 reachable and redirect HTTP to HTTPS.

TLS & protocol considerations

Tune TLS settings carefully. Removing older TLS versions improves security but may block very old clients. Example TLS line to restrict to modern versions:

ssl_protocols TLSv1.2 TLSv1.3;

Common errors and quick fixes

Symptom	Likely cause	Quick fix
`nginx -t` shows syntax error about `;`	Missing semicolon or brace	Fix the syntax and run `nginx -t` again
`nginx -t` shows directive not allowed here	Directive placed in wrong context (e.g., `http` inside `server`)	Move directive to appropriate context in `nginx.conf`
Site unreachable from internet but works locally	Cloud security group or external firewall blocks ports	Open ports 80/443 in cloud firewall and server firewall
Logs not created for site	Directory missing or wrong ownership	`mkdir -p /var/log/nginx/example.com && chown -R www-data:adm ...`
Connections drop on deploy	Using `restart` instead of `reload`	Use `nginx -s reload` after `nginx -t`

Final troubleshooting checklist

Run: nginx -t to validate syntax.
If nginx -t is OK: reload with nginx -s reload (or systemctl reload nginx).
Check logs in /var/log/nginx/ and per-site log directories.
Use curl locally (curl -I) to verify a working response.
Verify firewall and cloud security groups allow required ports.
If changing log paths, ensure directories exist and ownership is correct.
Confirm TLS settings are compatible with your clients.

Links and references

NGINX official docs: https://nginx.org/en/docs/
Systemd service control: https://www.freedesktop.org/software/systemd/man/systemctl.html
UFW documentation: https://help.ubuntu.com/community/UFW
curl manual: https://curl.se/docs/manpage.html

Thanks for reading — I appreciate it.

Introduction

Install & Config

Intermediate Config

Security

Performance

Conclusion

Demo Troubleshooting

Quick checks (first steps)

Always test configuration first: nginx -t

Context errors: directives must be in the right block

Apply changes gracefully: reload vs restart

Main configuration and logging

Per-site logging (recommended)

Verify reachability with curl

Hosts file for local resolution

Firewalls and cloud provider security

TLS & protocol considerations

Common errors and quick fixes

Final troubleshooting checklist

Links and references

Watch Video

​Quick checks (first steps)

​Always test configuration first: nginx -t

​Context errors: directives must be in the right block

​Apply changes gracefully: reload vs restart

​Main configuration and logging

​Per-site logging (recommended)

​Verify reachability with curl

​Hosts file for local resolution

​Firewalls and cloud provider security

​TLS & protocol considerations

​Common errors and quick fixes

​Final troubleshooting checklist

​Links and references

Watch Video

Quick checks (first steps)

Always test configuration first: nginx -t

Context errors: directives must be in the right block

Apply changes gracefully: reload vs restart

Main configuration and logging

Per-site logging (recommended)

Verify reachability with curl

Hosts file for local resolution

Firewalls and cloud provider security

TLS & protocol considerations

Common errors and quick fixes

Final troubleshooting checklist

Links and references