Initially I thought of this as a troubleshooting section for my nginx installation guide; however and given that as a beginner you will spend far more time fixing your configuration than installing anything, it grew into its own post, which I will keep updating over time with all the wonderful ways your web server can fail.

So here comes the part where it doesn’t work. You should check the error logs under /var/log/nginx and get familiar with them. First thing, are we actually hitting the server when we try to load the page?

tail -f /var/log/nginx/access.log

A line there with our IP means we indeed are. There will also be a response code, which ideally would be a 200 OK. There is also the famous 404 NOT FOUND or the many server errors which start with a 5, and we may encounter a 301 or 302 which mean there is a redirect.

NGINX is to blame

A 404 NOT FOUND error usually means you wrote your page’s root directory location wrong in the server context. It could also be due to having the wrong permissions in your files – the nginx user (normally www) must be able to read the contents of the root directory. We would fix that with:

chown -R www:www /path/to/mysite

PHP is to blame

If NGINX was able to read the index file but there’s something else wrong beyond there, you will often get a 501 (or similar error code), AKA Internal Server Error.

This is mostly due to NGINX being unable to process the file after reading it, and all fingers point to php being the culprit. The error log should point you in the right direction:

tail -f /var/log/nginx/error.log

Note that php scripts run from the shell or cron don’t get their errors shown here. To enable logging for those, find this line in /usr/local/etc/php.ini (if there is no such file, you may need to copy it from /usr/local/etc/php.ini-production)

log_errors = On
error_log = /var/log/php_errors.log

Errors from such scripts will then appear in this file.

Extensions

Tipically a newly installed php based site will be failing because it is missing some extensions. At times the error will make it clear which extension is missing; others, you will have to copy this error line in the Google search box to find out.

Extensions can be installed through the package repository by using this template:

php<version>-<name_of_the_extension>

For example, if we are using php 8.1 and we want to install the simplexml extension, we could try the following:

pkg install php81-simplexml

If the software you want to use requires a certain extension and you cannot find it in the package repository (pkg search <package>) there are chances its functionality has been integrated into the main nginx binary. The best way to find out is to just bring your site online and check what the logs say!

Deprecation woes

Another common cause of these errors is code that is simply written wrong. It may be your own code, or it may be someone else’s code, like for example, a WordPress plugin.

Outdated plugins can contain code that was written for older versions of PHP and will fail to run in a newer one because some function has been deprecated, which is programmers’ lingo for “deemed obsolete” by PHP mantainers. A deprecated error will then show in the error logs. You may choose to amend this code yourself, if the author hasn’t made an update available. Or, if all else fails, revert to an older version of PHP, which in FreeBSD is done by simply installing it:

pkg add php74

Remember to restart the php-fpm service after any changes you make in the configuration:

service php-fpm restart

And if we changed nginx.conf:

service nginx reload

The reload command prevents having downtime on our sites, or some user having a download interrupted because of our changes.