# Troubleshooting Craft CMS

Most Craft CMS problems involve file permissions, database configuration in `.env`, or out-of-sync project config. This page shows where to look and how to fix the issues you are most likely to encounter on TurboStack.

## Where to find the logs

Start with the application's own logs - Craft records detailed errors there before anything reaches the browser.

| Component | Where |
| --- | --- |
| Craft application log | `/var/www/<user>/[<app>/]craftcms/storage/logs/*.log` (and per-day subfolders) |
| Web server (Nginx) | Nginx access and error logs for the site's vhost |
| PHP-FPM | the PHP-FPM pool log for the site's per-user backend |
| Varnish | the system journal for the `varnish` service (when full-page caching is enabled) |
| Database | the MySQL error log on the host |

Beyond the logs, check the host's [Health](../../platform/hosts/health.md) tab for CPU, memory and disk pressure. Review recent deploys in [History](../../platform/hosts/revisions.md) to see whether a change coincides with when the problem started.

> [!TIP]
> Craft rotates its own logs under `storage/logs/`, so look there first - the newest file usually contains the stack trace for a 500 error.

## Common issues

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| HTTP 500 / blank page | A runtime exception; details suppressed in production | Read the newest file in `storage/logs/`; temporarily enable `devMode` on staging to surface the error |
| "Unable to write" / permission errors | `storage/`, `config/license.key` or `web/cpresources` not writable by the system user | Ensure these paths are owned by the system user and writable; clear `storage/runtime/` and let Craft recreate it |
| Cannot connect to database | Wrong credentials or driver in `.env` | Verify `CRAFT_DB_*` (driver, server, port, database, user, password) match the host's database; PostgreSQL needs `pgsql`, MySQL needs `mysql` |
| Changes not appearing / config out of sync | Project config differs between environments | Run `php craft project-config/apply`; commit `config/project/` and re-publish |
| Stale page after content edit | Varnish or static cache still holds the old page | Purge the relevant entry (Varnish supports `xkey` tag purges); `/admin` and `/actions` are never cached |
| Broken or missing image transforms | GD/ImageMagick missing or asset volume not writable | Confirm GD or ImageMagick is enabled in the PHP runtime and the asset/transform paths are writable; clear caches |
| Old assets / stale Cascading Style Sheets (CSS) after deploy | `web/cpresources` holds stale hashed assets | Clear `web/cpresources` and run `php craft clear-caches/all` |
| Queued jobs never finish | The queue is not being driven | Ensure the queue runs (web-triggered or via `php craft queue/run`); check `storage/logs/` for job failures |

## A troubleshooting workflow

1. Check the host's [Health](../../platform/hosts/health.md) tab for resource exhaustion (full disk, out-of-memory) that can cause 500s.
2. Read the relevant log - start with `storage/logs/`, then the Nginx and PHP-FPM logs for the vhost.
3. Check the last deploy in [History](../../platform/hosts/revisions.md); if a recent change broke the site, revert or re-publish it from [Publishing](../../platform/hosts/publishing.md).
4. Verify the supporting services are running and reachable - the web server, PHP-FPM, the database, Redis, and Varnish on the [Services](../../platform/hosts/services.md) tab.

## Getting help

If you are still stuck, gather the error from `storage/logs/`, the URL, and the time it occurred, then reach out via [Support](../../platform/support.md). The general [platform troubleshooting](../../platform/troubleshooting.md) guide covers host-wide issues that are not specific to Craft.

## Related

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