# Troubleshooting WordPress

Most WordPress problems on TurboStack come from a single change: a plugin or theme update, a caching layer, or a configuration edit. This page shows where the logs live, the issues you are most likely to hit, and a repeatable workflow to isolate the cause quickly.

## Where to find the logs

Read logs in the order a request travels: web server, then PHP, then WordPress, then the database.

| Component | Where |
| --- | --- |
| Nginx access/error | The host's Nginx log directory (per-vhost access and error logs) |
| PHP-FPM | The PHP-FPM pool log for the site's system user |
| WordPress (PHP) | `wp-content/debug.log` in the site's `public_html` (only when debug logging is enabled) |
| Varnish | The Varnish service log on the host (when `varnish_enabled`) |
| MySQL | The MySQL error/slow-query log on the host |
| Nginx vhost config | `/var/www/<user>/<app>/nginx/50main.conf` |
| wp-config.php | In the site's `public_html` (DB credentials, salts, `WP_DEBUG`) |

To capture PHP errors temporarily, set `WP_DEBUG` and `WP_DEBUG_LOG` to `true` in `wp-config.php`; this writes to `wp-content/debug.log`. Turn it off again on production. You can also see resource and service status on the host's [Health](../../platform/hosts/health.md) tab and recent deploys in [History](../../platform/hosts/revisions.md).

## Common issues

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| White screen / HTTP 500 | PHP fatal error from a plugin, theme or update | Enable `WP_DEBUG_LOG` and read `wp-content/debug.log`; deactivate the offending plugin/theme via wp-cli (`wp plugin deactivate <name>`) or by renaming its folder |
| "Error establishing a database connection" | Wrong credentials, or MySQL down/overloaded | Verify the `DB_*` values in `wp-config.php`, confirm MySQL is running in [Services](../../platform/hosts/services.md), check the MySQL log |
| Pages 404 except the home page | Rewrite/permalink rules lost | Re-flush permalinks: `wp rewrite flush --hard` (the platform sets `/%postname%/`); confirm the Nginx `try_files ... /index.php?$args` block |
| Stale content after editing | Full-page cache not purged | Install/configure the Proxy Cache Purge plugin so edits purge Varnish; check the `X-Cacheable` response header to see hits vs passes |
| Logged-in or cart pages caching wrongly | Page cache caching session traffic | Varnish already bypasses `wp-admin`/cart/`my-account`; avoid stacking a second page-cache plugin and verify custom URLs are in the bypass list |
| Redis object cache not connecting | Plugin misconfigured or Redis disabled | Enable Redis in [Services](../../platform/hosts/services.md) and reconnect the object-cache plugin; remove a stale `object-cache.php` drop-in if Redis is off |
| Media upload "exceeds the maximum" | PHP/nginx upload limits too low | Raise `upload_max_filesize`/`post_max_size` and the Nginx `client_max_body_size` for the site |
| Mixed-content warnings after HTTPS | URLs still stored as `http://` | Run `wp search-replace 'http://example.com' 'https://example.com'` and set the site/home URL to `https://` |

## A troubleshooting workflow

1. **Check [Health](../../platform/hosts/health.md)** - rule out CPU, memory, PHP-FPM or database saturation before chasing application bugs.
2. **Read the relevant log** - start with the Nginx error log and PHP-FPM/`debug.log` for 500s and white screens; the MySQL log for connection errors.
3. **Check the last deploy in [History](../../platform/hosts/revisions.md)** - if a recent change broke the site, revert and [Publish](../../platform/hosts/publishing.md) the previous working revision.
4. **Verify services are running** - confirm Nginx, PHP-FPM, MySQL and (if used) Redis and Varnish are up in [Services](../../platform/hosts/services.md); reload after config changes.

## Getting help

If the issue persists after these steps, reach out via [Support](../../platform/support.md). For platform-wide problems beyond WordPress itself, see the general [Troubleshooting](../../platform/troubleshooting.md) guide. Include the relevant log excerpts and the revision where the problem started.

## Related

- [Deploy WordPress](deploy.md)
- [WordPress best practices](best-practices.md)
- [Health](../../platform/hosts/health.md)
- [Support](../../platform/support.md)