Server & Gateway Errors

The 5xx family — these mean Nginx received the request fine, but something behind it (PHP-FPM, usually) didn't respond the way Nginx expected.

502 Bad Gateway

Common The single most common error you'll see running a PHP site. It means Nginx tried to hand the request to PHP-FPM and either got no response or an invalid one.

Check in this order:

1. Is PHP-FPM actually running?

aidipanel service:status

If the site's PHP-FPM version shows stopped or crashed:

aidipanel service:restart php8.4-fpm   # match the site's actual version

2. Does the site's error log name the actual problem?

aidipanel log:tail --domain example.com --type error

This is usually faster than guessing — look for PHP Fatal error, child exited with code, or unexpected FastCGI record.

3. Did a plugin or script just crash the PHP-FPM pool?

A plugin (WordPress) or package (Laravel) throwing a fatal error, hitting a memory limit, or segfaulting can take down that site's entire PHP-FPM pool — which then 502s every page on that site, not just the one that crashed, until the pool restarts.

# Restart just this site's pool
aidipanel service:restart php8.4-fpm

# If it immediately crashes again, something is fatally erroring on every request —
# check the error log, then deactivate the most recently changed plugin/theme:
cd /home/example/htdocs/example.com/wp-content/plugins
mv suspect-plugin suspect-plugin.disabled

A malformed response looks the same as a crash

An error like upstream sent unexpected FastCGI record: 3 in the Nginx error log means PHP-FPM sent back something Nginx couldn't parse as a valid response — not necessarily a crash. This is often caused by a plugin that outputs something before headers are sent (a stray echo, a BOM character at the top of a file, a warning printed to stdout instead of the log). If disabling a recently added/updated plugin resolves it, that plugin is almost certainly the cause — worth reporting upstream to the plugin author with this exact error string.

4. Check the socket path matches.

grep fastcgi_pass /etc/nginx/sites-available/example.com.conf
ls -la /run/php/

The socket named in the vhost (e.g. php8.4-fpm-example.sock) needs to actually exist in /run/php/. If it doesn't, PHP-FPM for that version/site combination isn't running — see step 1.

502 right after switching PHP versions

Common If this happens immediately after php:version --set, the vhost's socket reference and the actual running pool are momentarily out of sync — normally php:version handles this atomically, but if it was interrupted:

# Confirm what the site is actually configured for now
aidipanel php:version --domain example.com

# Confirm that version's FPM service is running
aidipanel service:status

# If needed, restart it explicitly
aidipanel service:restart php8.4-fpm

If the vhost still references the old version's socket path, re-run the version switch:

aidipanel php:version --domain example.com --set 8.4

503 Service Unavailable

Common Usually means PHP-FPM's pool is completely saturated — every worker is busy and new requests are being rejected rather than queued.

# Check current pool load
aidipanel php:info --version 8.4

If this happens under real traffic spikes rather than being a one-off, the PHP-FPM pool's pm.max_children may be too low for your server's RAM. This is a pool-level tuning setting in /etc/php/<version>/fpm/pool.d/<site-user>.conf — raise it cautiously and watch RAM usage, since each additional child process costs memory.

A 503 that only appears for a few seconds and then clears up on its own is often just a service restart in progress (Nginx or PHP-FPM reloading) — safe to ignore if it's brief and one-off.

500 Internal Server Error / white screen

Common Unlike a 502 (Nginx ↔ PHP-FPM communication problem), a 500 means PHP-FPM did respond, but the application itself hit a fatal error. WordPress often shows this as a blank white page rather than an actual "500" message — same underlying cause.

aidipanel log:tail --domain example.com --type error
# or, for WordPress specifically, if WP_DEBUG_LOG is enabled:
tail -f /home/example/htdocs/example.com/wp-content/debug.log

Most common causes, roughly in order of likelihood:

1. A plugin or theme update introduced a fatal error. Rename the plugin folder to disable it (see the 502 section above) and reload.
2. PHP memory limit exceeded. Look for Allowed memory size of ... exhausted in the log.
3. A PHP version incompatibility — code using a function or syntax removed in your current PHP version. Common after switching PHP major versions; see PHP Management.
4. A corrupted .htaccess-equivalent rule in the Nginx vhost, if you hand-edited it recently — check with nginx -t.

504 Gateway Timeout

Less common A specific request is taking longer to process than PHP-FPM's configured timeout allows, so Nginx gives up waiting.

Typical causes: a large file upload, a slow external API call inside the request (payment gateway, email service), an unoptimized database query, or a bulk import/export operation.

• If it's a one-off heavy operation (large media import, migration script), consider running it via SSH/WP-CLI directly instead of through the browser, which isn't bound by the same request timeout.
• If it's a specific recurring page, look at what that page does — this is almost always an application-level performance problem (a slow query, an external API with no timeout of its own) rather than something to fix at the server level.

Installer or install-time failures

If the installer itself fails partway through rather than a live site, the first stop is always:

cat /var/log/aidipanel-install.log

Common install-time snags:

• Installing on a server that already runs Nginx/Apache/MySQL — port 80/443 or 3306 conflicts with existing services. A fresh VPS avoids this entirely; see Installation → Requirements.
• Interrupted install (SSH disconnected mid-run) — inspect the install log before retrying. Do not run the installer over an installed panel; use sudo aidipanel self:update for an existing installation.
• Insufficient RAM/disk — installing MariaDB/MySQL + PHP + Nginx genuinely needs the minimum specs; a 512MB box can work but leaves very little headroom for an actual WordPress site on top.

Still stuck?

If the error log doesn't point anywhere obvious, nginx -t is worth running any time you suspect a config problem — it validates syntax and will refuse to reload on a broken config, which usually surfaces the exact line at fault:

nginx -t