8.10 Troubleshooting configuration problems

By Ravindra Bagale Last updated: 18 October 2026

Friends, if you changed a config and something broke, don't panic. Identify the symptom, find the cause in the table, and try one fix at a time – test after every fix.

Symptom	Likely cause	Fix
403 Forbidden after changing root	New folder outside `/var/www` without `<Directory>`/permissions; SELinux label wrong	`namei -l /path/index.html`; add `<Directory>` with `Require all granted`; CentOS: `semanage fcontext` + `restorecon -Rv`
Default welcome page instead of your site	Another block is `default_server` / loads first; `server_name` doesn't match	`sudo nginx -T \| grep -E "server_name\|listen"`; `sudo apachectl -S`; remove Ubuntu `default` / `000-default`
`nginx -t`: `unexpected "}"` or `directive is not terminated`	Missing `;` or `{`	Fix the line before the one reported
`Invalid command 'Require'` or `'#'`	Typo or inline comment in Apache	Put comments on their own line; check spelling
Service fails on new port: `Permission denied`	SELinux port not allowed (CentOS)	`semanage port -a -t http_port_t -p tcp PORT`
New port not reachable from browser	Security group / firewalld not opened	Add inbound rule; `firewall-cmd --add-port`
`Address already in use`	Both Nginx and Apache on port 80	`sudo ss -tlnp \| grep :80`; stop one
Changes have no effect	Not reloaded; edited a `.bak` or wrong file	`sudo nginx -T` shows what is really loaded
Downloads PHP file instead of running it	PHP handler not configured	See Chapter 10 (PHP-FPM)

Ravindra Bagale's Tip

Many students keep re-reading the config when there is a problem, but never run sudo nginx -T or sudo apachectl -S. These commands show the config the server has actually loaded – not the one you edited. Look at that first.

Ravindra Bagale's Tip – मराठी

खूप students problem आला की config परत परत वाचत बसतात, पण sudo nginx -T किंवा sudo apachectl -S चालवत नाहीत. हे commands server ने खरंच load केलेला config दाखवतात – तुम्ही edit केलेला नाही. आधी तेच बघा.

Ravindra Bagale's Tip – हिंदी

बहुत students problem आने पर config बार-बार पढ़ते रहते हैं, पर sudo nginx -T या sudo apachectl -S नहीं चलाते. ये commands server ने सच में load की हुई config दिखाते हैं – तुमने edit की हुई नहीं. पहले वही देखो.

Lab

Chala, muddam Apache vhost madhe Require all granted # allow all asa inline comment lihun sudo apachectl configtest chalva aani error vacha. Mag comment vegalya line var halva aani test pass hoto ka te bagha.

How to think while troubleshooting

Write down the exact symptom: the status code, the page you see, the error line.
Ask "what changed?" Most problems follow a change.
Check one layer at a time: DNS → security group → web server → app → database.
Change one thing, test, then decide.

Check from left to right. The first layer that fails is where to fix.

Status codes mapped to stacks

The same code can have different causes depending on what sits behind the web server.

502 with Node.js / PM2

The app is down or on another port.

pm2 status; curl -I 127.0.0.1:3000

What you see:

curl: (7) Failed to connect

502 with Python / Gunicorn

Wrong socket path or a crashed worker.

sudo journalctl -u gunicorn -n 20

What you see:

ModuleNotFoundError: No module named 'app'

502 with PHP-FPM

The socket does not match or FPM is stopped.

sudo tail /var/log/nginx/error.log

What you see:

connect() to unix:/run/php-fpm/www.sock failed (2: No such file or directory)

502/503 with Tomcat (Java)

Tomcat is still starting (Spring Boot can take a while) or ran out of memory.

sudo tail logs/catalina.out

What you see:

java.lang.OutOfMemoryError: Java heap space

502 with .NET / Kestrel

The app crashed at startup, often because of a missing config value.

sudo journalctl -u api -n 20

What you see:

Unhandled exception. System.InvalidOperationException

504 from any stack

Slow database: MySQL, PostgreSQL or MongoDB.

SHOW PROCESSLIST;  /  SELECT * FROM pg_stat_activity;

What you see:

Long-running query visible

403 on CentOS / RHEL

SELinux label.

ls -Z /srv/site

What you see:

unconfined_u:object_r:var_t  (should be httpd_sys_content_t)

Real examples

Indian company (sample): a Paytm-style team saw 504s every evening at 8 pm. The cause was a report query on the same MySQL server. Moving reports to a read replica fixed it. Everyday: if a tap has no water, you check the tank, then the pipe, then the tap. You do not replace the tap first.

Recap

Symptom, then "what changed?", then layer by layer.
Read the right log for your stack.