# Troubleshooting Magento

Most Magento problems have a few common causes: stale caches, invalid indexers, a stopped cron, a search-engine connection, or the site stuck in maintenance mode. This page shows where to look and how to fix the common cases. Many fixes use Magento's CLI (`bin/magento`) or the diagnostic tool `n98-magerun2`, both available from your app root.

## Where to find the logs

Your Magento app lives at `/var/www/<user>/public_html` (the vhost serves its `pub/` subdirectory). The most useful logs are:

| Component | Where |
| --- | --- |
| Magento application | `/var/www/<user>/public_html/var/log/` (`system.log`, `exception.log`, `debug.log`) |
| Magento cron | `var/log/magento.cron.log` and `var/log/setup.cron.log` |
| Reports / fatal errors | `/var/www/<user>/public_html/var/report/` |
| Nginx access/error | the host's web server logs (under the system user's home / `/var/log/`) |
| PHP-FPM | the PHP-FPM pool log for the app's runtime |
| Database (MySQL) | the MySQL error/slow-query log |
| Varnish | the Varnish service log |

All files under `var/log/` are rotated weekly. You can also use the host's [Health](../../platform/hosts/health.md) tab for resource graphs and check recent deploys under [History](../../platform/hosts/revisions.md).

## Common issues

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| Site shows "service unavailable" / maintenance page | Maintenance mode left enabled (often after a failed deploy) | `bin/magento maintenance:status`, then `bin/magento maintenance:disable` |
| Old content, changed config or prices not showing | Stale cache | `bin/magento cache:flush` (and `cache:clean`) |
| Catalog/prices wrong, "indexer invalid" warning | Indexers out of date | `bin/magento indexer:status`, then `bin/magento indexer:reindex` |
| Storefront errors, empty search results | Elasticsearch/OpenSearch down or misconfigured | Verify the service is running on [Services](../../platform/hosts/services.md); re-check the search engine host and index prefix in admin |
| Emails, reindex, or scheduled jobs never run | Cron not running | Confirm the cron jobs exist for the system user and read `var/log/magento.cron.log`; run `bin/magento cron:run` manually to test |
| 503 errors from the storefront | Varnish backend (PHP/nginx) down, or wrong Varnish hosts | Check PHP-FPM/nginx are up; verify Magento's `http-cache-hosts` and Varnish backend port (8080) settings |
| White screen / blank pages, permission errors | Wrong file permissions or stale generated code | Fix ownership of `var/`, `generated/`, `pub/static`; clear with `rm -rf generated/* var/cache/*` then `setup:di:compile` |
| Admin/storefront very slow | Running in developer mode in production | `bin/magento deploy:mode:set production` |
| Indexer stuck or failing repeatedly | Corrupted indexer state | `bin/magento indexer:reset`, then `indexer:reindex`; in production set indexers to cron-driven with `indexer:set-mode schedule` |
| Missing or stale CSS/JS in the storefront | Static content not deployed | `bin/magento setup:static-content:deploy -f` (`-f` forces the deploy even in developer mode) |
| Stock quantities wrong after orders or returns | Inventory reservations inconsistent | `bin/magento inventory:reservation:list-inconsistencies`, then `inventory:reservation:create-compensations` |
| Locked out of the admin | Too many failed admin logins | `bin/magento admin:user:unlock <username>` |

## A troubleshooting workflow

1. **Check [Health](../../platform/hosts/health.md)** - rule out resource exhaustion (CPU, memory, disk) and confirm the host is up.
2. **Read the relevant log** - start with `var/log/exception.log` and `var/log/system.log`, plus the nginx/PHP-FPM logs for HTTP-level errors.
3. **Check the last deploy in [History](../../platform/hosts/revisions.md)** - if a recent change broke the site, revert or re-publish a known-good revision via [Publishing](../../platform/hosts/publishing.md).
4. **Verify services are running** - on [Services](../../platform/hosts/services.md) confirm MySQL, Elasticsearch/OpenSearch, Redis, and Varnish are all up; then re-run `cache:flush` and `indexer:reindex` and re-test.

## Getting help

If you are still stuck, reach out via [Support](../../platform/support.md), or work through the platform-wide [Troubleshooting](../../platform/troubleshooting.md) guide for issues that are not Magento-specific.

## Related

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