Troubleshooting

Find your symptom below. Each row links to the specific fix — you don't need to read a whole page to solve one problem.

By symptom

Symptom	Likely cause	Go to
502 Bad Gateway	PHP-FPM crashed, wrong socket path, or a plugin/script fatally erroring	Server Errors
503 Service Unavailable	PHP-FPM pool overwhelmed, or a service was mid-restart	Server Errors
500 Internal Server Error / white screen	PHP fatal error — usually a plugin, theme, or .htaccess-equivalent issue	Server Errors
504 Gateway Timeout	A request is taking longer than PHP-FPM's timeout to finish	Server Errors
502 right after switching PHP versions	Vhost still pointing at the old version's socket	Server Errors
"This site can't be reached" / DNS error	DNS not pointed at the server, or hasn't propagated yet	Domain & SSL Issues
Browser SSL warning on the panel (port 8443)	Expected — the panel UI uses a self-signed cert	Domain & SSL Issues
Browser SSL warning on your actual site	SSL not installed yet, or the cert doesn't cover www	Domain & SSL Issues
ssl:install fails with "challenge failed"	Port 80 blocked, or DNS not propagated	Domain & SSL Issues
"Too many certificates" error	Hit Let's Encrypt's rate limit while testing	Domain & SSL Issues
Edited a post/menu but the live site didn't change	FastCGI Cache serving a stale page	Cache & Performance
Site feels slow despite cache being on	Low hit rate, or cache not actually enabled for that domain	Cache & Performance
Logged-in users seeing cached/stale content	Expected — logged-in traffic always bypasses cache, this is a different problem	Cache & Performance
"Error establishing a database connection"	Wrong DB credentials in wp-config.php/.env, or MySQL/MariaDB is down	Permissions & Database
Can't upload images / plugin install fails ("unable to create directory")	File ownership wrong after a manual file transfer	Permissions & Database
403 Forbidden	Permission bits too restrictive, or an Nginx deny rule matching unexpectedly	Permissions & Database
site:delete --purge refuses to remove a user	The .aidipanel-managed marker is missing or was edited	Permissions & Database

By area

Server & Gateway Errors → 502, 503, 500, 504 — the HTTP error codes that mean "something upstream broke."

Domain & SSL Issues → DNS propagation, certificate installation, browser warnings, rate limits.

Cache & Performance → Stale content, purge behavior, hit rate, and general speed troubleshooting.

Permissions & Database → File ownership, upload failures, database connection errors, guarded delete.

General first steps for anything

Before diving into a specific page, these two commands answer "is it actually broken, and where":

# Is everything actually running?
aidipanel service:status

# What does this site's own error log say? (usually the fastest answer)
aidipanel log:tail --domain example.com --type error

The per-site error log especially — /var/log/nginx/<domain>-error.log — will usually name the exact problem (a missing PHP extension, a permission-denied path, a timeout) rather than leaving you to guess from just the HTTP status code.