Connection Refused and Other Nginx Errors: A Deploynix Troubleshooting Guide

Your Laravel application runs behind Nginx, and when something goes wrong in the communication between Nginx, PHP-FPM, and your application code, the errors are often cryptic. A "502 Bad Gateway" tells you almost nothing about the actual problem. A "Connection Refused" could point to a dozen different causes.

This guide covers the most common Nginx errors you will encounter with a Laravel application managed by Deploynix, explains what is actually happening at the system level, and walks you through diagnosing and fixing each one.

How the Request Path Works

Before debugging, you need to understand the request flow:

1. A user's browser sends an HTTPS request
2. Nginx receives the request on port 443 (or 80, redirecting to 443)
3. For static files (CSS, JS, images), Nginx serves them directly
4. For PHP requests, Nginx passes the request to PHP-FPM via a Unix socket
5. PHP-FPM spawns or reuses a worker process to execute your Laravel application
6. The response travels back: PHP-FPM to Nginx to the user's browser

Errors can occur at every transition in this chain. The error you see in the browser hints at where the chain broke.

502 Bad Gateway

What the user sees:

A white page with "502 Bad Gateway" and the Nginx version.

What it means:

Nginx successfully received the request but could not get a valid response from PHP-FPM. Nginx is working; PHP-FPM is not.

Common causes and fixes:

PHP-FPM Is Not Running

The most straightforward cause. PHP-FPM has crashed or was stopped.

Diagnosis:

systemctl status php8.4-fpm

If the status shows "inactive" or "failed," PHP-FPM is down.

Fix:

systemctl restart php8.4-fpm

Check the PHP-FPM log for why it stopped:

tail -50 /var/log/php8.4-fpm.log

Common reasons: a segfault in a PHP extension, OOM killer terminated the master process, or a configuration error after a PHP update.

In Deploynix, you can restart PHP-FPM through the server dashboard without SSH access. If PHP-FPM repeatedly crashes, check Deploynix's monitoring for memory pressure — the OOM killer frequently targets PHP-FPM when the server runs out of RAM.

Socket Mismatch

Nginx is configured to pass requests to a PHP-FPM socket path that does not match where PHP-FPM is actually listening.

Diagnosis:

Check the Nginx site configuration for the socket path:

grep fastcgi_pass /etc/nginx/sites-enabled/*

Then check where PHP-FPM is actually listening:

grep listen /etc/php/8.4/fpm/pool.d/www.conf

If these do not match, Nginx cannot reach PHP-FPM.

Fix:

Align the socket paths. In Deploynix-managed servers, the socket path is configured consistently during provisioning. This mismatch typically occurs only when server configuration has been manually edited. If you have modified PHP-FPM or Nginx configuration files manually, restore the Deploynix defaults or ensure the socket paths match.

PHP-FPM Workers Are All Busy

Every PHP-FPM worker is processing a request, and new requests queue up until Nginx's timeout is reached.

Diagnosis:

grep "server reached pm.max_children" /var/log/php8.4-fpm.log

If you see this message, all workers are exhausted.

Fix:

Increase pm.max_children in the PHP-FPM pool configuration, but only if your server has the RAM to support more workers. Each worker consumes 30-80 MB depending on your application. On a 2 GB server with MySQL and Valkey also running, 5-8 workers is typically the maximum.

If you cannot add more workers, identify what is keeping workers busy. Long-running requests (slow database queries, external API calls) tie up workers. Move slow operations to queue jobs so web requests complete quickly.

504 Gateway Timeout

What the user sees:

"504 Gateway Timeout" after a long wait (usually 30-60 seconds).

What it means:

Nginx waited for PHP-FPM to respond, but the response did not arrive within the configured timeout. The request might still be processing in PHP-FPM, but Nginx gave up waiting.

Common causes and fixes:

Slow Database Queries

The most frequent cause. A query that takes 45 seconds ties up a PHP-FPM worker and eventually triggers Nginx's timeout.

Diagnosis:

Enable the MySQL slow query log:

SET GLOBAL slow_query_log = 'ON';
SET GLOBAL long_query_time = 2;

Check for slow queries:

tail -100 /var/log/mysql/mysql-slow.log

Fix:

Optimize the query. Common issues in Laravel applications:

• Missing database indexes on columns used in where(), orderBy(), and join() clauses
• N+1 query problems: use with() for eager loading
• Loading entire tables into memory: use chunk() or cursor() for large datasets
• Missing select() clause: loading all columns when you only need a few

External API Calls in Web Requests

If your controller makes a synchronous HTTP call to a third-party API, and that API is slow or unresponsive, the request will timeout.

Fix:

Move external API calls to queue jobs. The web request should dispatch the job and return immediately (or show a "processing" state to the user). The queue worker handles the slow API call in the background.

If the API call must happen synchronously (e.g., payment processing during checkout), set appropriate timeouts on the HTTP client:

Http::timeout(10)->post('https://api.example.com/charge', $data);

Nginx Timeout Configuration

If legitimate operations need more than the default timeout (60 seconds), you can increase Nginx's proxy timeout. However, this is usually the wrong fix — the right fix is to make the operation faster or move it to a background job.

If you must increase the timeout:

fastcgi_read_timeout 120;

In Deploynix, Nginx configuration is managed through the server dashboard. Modifying timeout values is possible but should be a last resort.

Connection Refused

What the user sees:

The browser shows "This site can't be reached" or "Connection refused" — no Nginx error page at all.

What it means:

Nothing is listening on port 80 or 443. This is different from a 502 (where Nginx is running but PHP-FPM is down). Here, Nginx itself is not responding.

Common causes and fixes:

Nginx Is Not Running

Diagnosis:

systemctl status nginx

Fix:

systemctl restart nginx

If Nginx fails to start, check the error log:

nginx -t

This tests the configuration and reports any syntax errors. A missing semicolon or an invalid directive in any included configuration file prevents Nginx from starting.

Firewall Blocking the Port

Deploynix configures firewall rules during server provisioning, opening ports 80 and 443 for web traffic. If the firewall was modified manually or by another tool, these ports might be blocked.

Diagnosis:

ufw status

Check that ports 80 and 443 show "ALLOW" from anywhere.

Fix:

ufw allow 80
ufw allow 443

In Deploynix, firewall rules are managed through the dashboard. Review your firewall rules to ensure HTTP and HTTPS traffic is allowed.

DNS Not Pointing to the Server

If you recently created a site or changed DNS records, the domain might not resolve to your server's IP yet.

Diagnosis:

dig +short yourdomain.com

Compare the returned IP with your server's IP in the Deploynix dashboard.

Fix:

Update your DNS records to point to the correct IP. DNS propagation can take minutes to 48 hours, though most changes propagate within an hour.

Deploynix's vanity domains (*.deploynix.cloud) are pre-configured and do not require manual DNS setup, making them useful for quick testing when you suspect a DNS issue.

403 Forbidden

What the user sees:

"403 Forbidden" — Nginx is running and received the request, but is refusing to serve it.

What it means:

Nginx does not have permission to access the requested file, or the directory index is forbidden.

Common causes:

Incorrect File Permissions

Nginx runs as the www-data user. If your application files are not readable by this user, Nginx returns 403.

Diagnosis:

ls -la /home/deploynix/your-site/current/public/

The public directory and its contents should be readable by www-data (typically through group permissions).

Fix:

chown -R deploynix:www-data /home/deploynix/your-site/current/public
chmod -R 755 /home/deploynix/your-site/current/public

Missing Index File

If the public/index.php file is missing (failed deployment, incorrect web root configuration), Nginx tries to list the directory and, with autoindex off (the default), returns 403.

Diagnosis:

ls -la /home/deploynix/your-site/current/public/index.php

If the file does not exist, the deployment did not complete correctly.

Fix:

Re-deploy through Deploynix, or check that your site's web directory is set to /public in the site configuration.

413 Request Entity Too Large

What the user sees:

"413 Request Entity Too Large" when uploading a file.

What it means:

The uploaded file exceeds Nginx's client_max_body_size limit.

Fix:

Increase the limit in the Nginx site configuration:

client_max_body_size 100M;

Also check PHP's limits:

upload_max_filesize = 100M
post_max_size = 100M

Both Nginx and PHP limits must accommodate your maximum upload size. In Deploynix, PHP settings can be adjusted through the server's PHP configuration panel.

SSL/TLS Errors

ERR_SSL_PROTOCOL_ERROR

The browser cannot establish an SSL connection. Common causes:

• SSL certificate not installed or expired
• Nginx is not configured to listen on port 443
• Mixed HTTP/HTTPS configuration

Diagnosis:

Check if the certificate files exist:

ls -la /etc/nginx/ssl/

Test the SSL configuration:

nginx -t

In Deploynix, SSL certificates are auto-provisioned through Let's Encrypt or vanity domain certificates. If a certificate expires, Deploynix automatically renews it. Check the SSL status in your site's settings.

ERR_CERT_AUTHORITY_INVALID

The certificate is self-signed or the certificate chain is incomplete. This should not occur with Deploynix's Let's Encrypt integration, which provides properly chained certificates. If you see this error, the certificate may have been manually replaced with an incomplete chain.

A Systematic Debugging Approach

When you encounter an Nginx error, follow this sequence:

1. Identify the error code — 502, 504, 403, and "Connection Refused" each point to different parts of the stack
2. Check Nginx status — systemctl status nginx — is it running?
3. Check PHP-FPM status — systemctl status php8.4-fpm — is it running?
4. Test Nginx configuration — nginx -t — is the config valid?
5. Check error logs — /var/log/nginx/error.log and /var/log/php8.4-fpm.log
6. Check Deploynix monitoring — Look for CPU, memory, or disk alerts that correlate with the error timing
7. Check recent deployments — Did a recent deployment change Nginx or PHP configuration?

Most issues resolve at step 2 or 3 (a service needs restarting) or step 5 (the logs reveal the specific cause). Deploynix's web terminal gives you access to run these diagnostic commands directly from your browser without setting up SSH.

Conclusion

Nginx errors are the visible symptoms of deeper issues — PHP-FPM resource exhaustion, slow application code, misconfigured permissions, or network problems. The error code narrows down where in the request chain the failure occurred, and the server logs tell you exactly what went wrong.

Deploynix handles the most common configuration issues during provisioning and provides monitoring to catch resource problems before they cause user-facing errors. But when errors do occur, understanding the Nginx-to-PHP-FPM-to-Laravel chain gives you the knowledge to diagnose and fix them in minutes rather than hours.

Keep this guide handy. The errors in it account for the vast majority of Nginx-related issues you will ever encounter with a Laravel application.