500 Internal Server Error in NGINX: PHP-FPM and Internal Causes

If you ever got the “500 Internal Server Error” page served by your NGINX web server, it may be puzzling what is really wrong from the page itself:

Understanding why you get the NGINX error can be challenging.

In this post I will cover the two main reasons for this error:

• Upstream related issues, such as caused by faulty PHP scripts
• Truly internal NGINX problems.

We’ll explore each category with examples and solutions to give you a complete understanding.

1. Upstream related issues causing 500 errors

In terms of NGINX, an upstream is any backend service that NGINX is configured to, in order to fetch the page content.
I will use PHP-FPM as example upstream, as it’s still quite popular.

PHP-FPM is an important part of many NGINX setups, especially when dealing with PHP websites like WordPress.
NGINX acts as a reverse proxy, routing requests to PHP-FPM for processing.

A common scenario causing internal server error page being served by NGINX is a faulty PHP script with syntax errors or runtime PHP exceptions. Such issues can trigger a 500 error like the image above, particularly when fastcgi_intercept_errors setting is on in NGINX. This configuration makes NGINX treat upstream errors as its own, thus instead of seeing errors generated by PHP, you see the error generated by NGINX itself.

Solution for 500 internal server error in NGINX caused by PHP:

Simply fixing your PHP scripts will get rid of the error in NGINX.

For an over-simplified example, this PHP script snippet contains a syntax error, which missing trailing semicolon:

<?php
echo "Hello, World"

When NGINX configured with:

location ~ \.php$ {
    error_page 500 /500.html;
    fastcgi_intercept_errors on;

    fastcgi_pass unix:/path/to/php-fpm.sock;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    include fastcgi_params;
    ...
}

The script will cause NGINX to emit the 500 error.

The correct script will solve the issue:

<?php
echo "Hello, World";

In a real website with complex PHP scripts, you will want to:

• Enable PHP Error Logging: Configure PHP to log errors for detailed insights.
• Debug and fix the PHP Script: Use tools like Xdebug to identify and fix issues in the script.

Implementing effective error handling

Some errors in PHP can be tolerated and dealt with using the mechanism of exception handling. This is applicable for cases of communicating with external API services, where you can’t guarantee that external services are available and fault-tolerant all the time. Proper error handling in such PHP scripts can prevent many 500 errors.

Catch exceptions and handle errors gracefully to avoid passing them up to NGINX. An example code snippet for error handling:

try {
    // Code that may throw an exception, e.g. talking to external API
} catch (Exception $e) {
    error_log($e->getMessage());
    // Handle the exception
}

2. Truly internal NGINX issues

Internal server problems in NGINX

Apart from PHP-FPM and other upstream issues, NGINX itself can encounter issues leading to a 500 error. These are often related to resource allocation failures or internal logic errors. While we speak of such errors as “internal server errors”, they are in fact more related to issues of the server environment where NGINX runs. Those are rarely, if ever, actually fault of NGINX.

Example: memory allocation failure

NGINX dynamically allocates memory while processing request input, and delivering response. Such allocation in NGINX source code is done often this way:

b = ngx_calloc_buf(r->pool);
if (b == NULL) {
    return NGX_HTTP_INTERNAL_SERVER_ERROR;
}

In this code, NGINX attempts to allocate a buffer for the response using ngx_calloc_buf(r->pool). It then makes a failure check: if the allocation fails (b == NULL), then NGINX returns an internal server 500 error. This indicates an actual server issue where NGINX cannot allocate the necessary memory.

The solution is to:

• make sure there is enough available RAM, for example, by running free -h
• optimize server configuration for memory-hungry applications, e.g. by tuning the number of PHP-FPM workers or number of allowed connections/buffers in MySQL
• ensure swap configuration for handling traffic spikes
• upgrade server’s RAM, if needed

To proactively prevent the error in the future, monitor server resources using tools like NGINX Amplify.

Handling read and write events

NGINX’s handling of read and write events can also lead to 500 errors if it encounters problems during these operations.

Example: Read event handling failure

Consider this excerpt from NGINX source code:

if (ngx_handle_read_event(r->connection->read, 0) != NGX_OK) {
    return NGX_HTTP_INTERNAL_SERVER_ERROR;
}

In that snippet, NGINX tries to handle a read event. If handling the read event fails, NGINX returns a 500 error. This suggests an internal server problem in managing client connections or data processing.

For the correct solution, dig into the output of dmesg, check NGINX error logs, as well as observe the current CPU utilization.

For example, the number of NGINX’s worker processes can impact resource usage. If you have too many worker processes configured, it can strain system resources. Adjust the worker_processes directive in your NGINX configuration based on your server’s capacity. Value auto is a sane default.

Another possible reason is if the system’s limit on file descriptors is reached, it can lead to the same dreaded 500 error. This can be solved by supplying larger worker_rlimit_nofile setting in NGINX configuration:

• use the ulimit -n command to check the current file descriptor limit for the NGINX user.
• ensure that the worker_rlimit_nofile value is set higher than or equal to this limit, e.g. worker_rlimit_nofile 4096;

The internal error 500 emitted by NGINX can also be caused by workload, and depending on your logs analysis, you might need to set up load balancing or perform a server upgrade to solve the problem. Before you do, ensure your cache setup is optimal, and that you use a good full-page cache solution, like Varnish Cache.

Conclusion: solving the 500 internal server error in NGINX

The 500 internal server error in NGINX can stem from PHP-FPM issues or NGINX’s server environment internal problems, often related to resource handling or internal logic. Understanding these distinct causes is crucial for effective troubleshooting and resolution.

FAQs: Quick insights into common questions

1. When should I suspect a PHP-FPM issue in a 500 error scenario?
   If the error occurs during the execution of a PHP script, especially when fastcgi_intercept_errors is on, it’s likely a PHP-FPM related issue.

2. What are common indicators of internal NGINX problems leading to 500 errors?
   Look for errors related to memory allocation failures or issues in handling client connections in NGINX logs.

3. How can I prevent PHP-FPM related 500 errors?
   Implement robust error handling in your PHP scripts and ensure PHP-FPM is correctly configured.

4. What steps can I take to minimize internal NGINX 500 errors?
   Regularly monitor server resources, optimize NGINX configurations, and ensure the server is not overloaded.

5. Is it important to keep NGINX and PHP-FPM updated?
   Absolutely. Regular updates can fix known bugs and improve performance, reducing the likelihood of 500 errors. NGINX Extras provide complete solution for production-grade, premium NGINX core and modules packages, allowing to upgrade your NGINX server from a simple web server to complete stack with Brotli, PageSpeed, ModSecurity and over a hundred more NGINX module packages. All packages are carefully maintained and can be easily upgraded with just yum upgrade.

Understanding and resolving the 500 internal server error in NGINX requires a combination of PHP script knowledge and NGINX server management skills. With this guide, you’re well-equipped to diagnose and address these errors effectively.