# Troubleshooting Drupal

When a Drupal site is not working correctly on TurboStack, the cause is usually visible in a log or resolved by clearing a cache. This page shows where to look and how to fix the most common problems. Because Drupal is configuration-only on the platform, most application errors come from your code, modules, or database rather than the platform itself.

## Where to find the logs

Work from the front of the request to the back: web server, PHP, then Drupal itself.

| Component | Where |
| --- | --- |
| Nginx access/error | The host's web server logs, surfaced on the [Health](../../platform/hosts/health.md) tab; per-app config lives in `nginx/50main.conf` under the app directory |
| PHP-FPM | The PHP-FPM pool log for your user/app - start here for fatal PHP errors and timeouts |
| Varnish | `journalctl -u varnish` (and `varnishlog`) when full-page caching is enabled |
| Drupal log (dblog) | `drush watchdog:show` / `drush ws`, or **Reports > Recent log messages** in the admin UI |
| PHP error log | Drupal's configured error log / the PHP-FPM error log - the place to find a white-screen stack trace |
| Database | MySQL service status and slow query log via [Health](../../platform/hosts/health.md) and [Services](../../platform/hosts/services.md) |

> [!TIP]
> Connect over [SSH](../../platform/hosts/ssh.md) and run Drush from your site root. `drush status` confirms the database connection, bootstrap level, and active config; it is the fastest first check.

## Common issues

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| White screen of death (blank page) | Uncaught PHP error or fatal | Read the PHP/PHP-FPM error log or `drush watchdog:show`; temporarily set `$config['system.logging']['error_level'] = 'verbose';` in `settings.php` to reveal the trace |
| Stale content or "page not found" after a deploy | Drupal caches not rebuilt | Run `drush cr` to rebuild caches; for Varnish, invalidate via the Advanced Varnish module or restart Varnish |
| "Database connection failed" / install screen appears | Wrong credentials or DB not reachable | Verify the `$databases` settings in `settings.php` against the host [Credentials](../../platform/hosts/credentials.md); confirm MySQL is running in [Services](../../platform/hosts/services.md) |
| "Unable to write" / file upload errors | Permissions on `sites/default/files` | Ensure the files directory is owned by your system user and writable; private files must sit outside the web root |
| Changes not appearing for anonymous visitors | Varnish serving cached pages | Confirm the Advanced Varnish module is installed so cache-tag `BAN` works; clear the relevant tags or flush Varnish |
| Scheduled jobs not running | Cron not firing | Schedule `drush cron` as a [host cron task](../../platform/hosts/services.md) instead of relying on web cron; check its log |
| Slow pages or 502/504 errors | PHP timeouts, no object cache, or DB pressure | Enable Redis + Varnish, profile slow queries, and raise sizing only with evidence (see [Best practices](best-practices.md)) |

> [!WARNING]
> A failed `drush updb` or config import can leave the site in a broken state. Always back up the database first via [Backups](../../platform/hosts/backups.md).

## A troubleshooting workflow

1. **Check [Health](../../platform/hosts/health.md).** Confirm CPU, memory, and disk are not exhausted and that Nginx, PHP-FPM, MySQL, and (if used) Varnish/Redis are running.
2. **Read the relevant log.** Use the table above - PHP-FPM/error log for white screens, dblog for application errors, Varnish for stale-cache symptoms.
3. **Review the last deploy.** Open [History](../../platform/hosts/revisions.md). If a recent change broke the site, revert or re-publish the previous working configuration from [Publishing](../../platform/hosts/publishing.md).
4. **Verify services and clear caches.** Confirm services are enabled in [Services](../../platform/hosts/services.md), then run `drush cr`. If only anonymous users see stale pages, flush Varnish.

## Getting help

If the site is still down after these steps, gather the error message, the relevant log excerpt, and what changed (deploy, module update, config import). Then reach out via [Support](../../platform/support.md). The general [platform troubleshooting](../../platform/troubleshooting.md) guide covers host-level issues that are not specific to Drupal.

## Related

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