# Troubleshooting Laravel

When a Laravel application is not working correctly on TurboStack, the cause is almost always visible in a log. This page shows where the logs live, the most common problems and their fixes, and a repeatable workflow to follow. Because Laravel is a [configuration-only application](deploy.md), most fixes are Artisan commands or `.env` changes you run against your own deployed code.

## Where to find the logs

Replace `<user>` with the host's system user and `<app>` with the application name (omit the `_<app>` suffix if the app has no name set).

| Component | Where |
| --- | --- |
| Nginx access log | `/var/log/nginx/<user>_<app>.log` |
| Nginx error log | `/var/log/nginx/error.log` |
| PHP / PHP-FPM errors | `/var/log/php/<user>_<app>.log` |
| Laravel application log | `/var/www/<user>/<app>/storage/logs/laravel.log` |
| Queue workers (supervisor) | `/var/www/<user>/.config/supervisor/log/` |
| Database | Managed MySQL service - see [Services](../../platform/hosts/services.md) |

Also use the host's [Health](../../platform/hosts/health.md) tab for service status and resource graphs, and check recent deploys in [History](../../platform/hosts/revisions.md) - a broken page often coincides with the last publish.

> [!TIP]
> The Laravel log only fills up if logging works. If `storage/logs/laravel.log` is empty during a 500, the error happened before Laravel booted - look in the PHP-FPM log instead.

## Common issues

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| HTTP 500, blank page | Application exception; details suppressed in production | Read `storage/logs/laravel.log`, then the PHP-FPM log; fix the underlying error. |
| "No application encryption key" / 500 on boot | Missing or invalid `APP_KEY` | Set a valid key with `php artisan key:generate`, then `php artisan config:clear`. |
| `.env` change has no effect | Stale compiled config cache | Run `php artisan config:clear` (and re-run `config:cache` after). |
| Old routes/views served, "class not found" | Stale route/view/autoload caches after deploy | `php artisan route:clear && php artisan view:clear && php artisan cache:clear`; `composer dump-autoload`. |
| Database / migration errors | Pending migrations or wrong DB credentials | Verify `.env` DB settings against [Services](../../platform/hosts/services.md); run `php artisan migrate --force`. |
| Jobs never run, queue backs up | No worker running, or wrong queue connection | Check `QUEUE_CONNECTION`; start `php artisan queue:work` under supervisor and inspect its log. |
| Scheduled tasks not firing | Scheduler cron not calling Laravel | Ensure a cron entry runs `php artisan schedule:run` every minute. |
| "Permission denied" writing cache/logs | `storage/` or `bootstrap/cache/` not writable | Make those directories writable by the system user; clear and rebuild caches. |

> [!WARNING]
> Never set `APP_DEBUG=true` to read errors on a live site - it exposes stack traces and secrets. Read the logs instead and keep `APP_DEBUG=false` in production.

## A troubleshooting workflow

1. **Check [Health](../../platform/hosts/health.md)** - confirm the host is up and PHP, MySQL and Redis services are running before digging into code.
2. **Read the relevant log** - start with `storage/logs/laravel.log`; if it is silent, read the PHP-FPM log (`/var/log/php/<user>_<app>.log`) and the Nginx error log.
3. **Check the last deploy** - review recent changes in [History](../../platform/hosts/revisions.md). If a publish broke the site, revert or re-publish a known-good revision via [Publishing](../../platform/hosts/publishing.md).
4. **Verify services and caches** - confirm queue workers are alive in supervisor, then clear and rebuild Laravel caches (`php artisan optimize:clear` followed by `php artisan optimize`) once the fix is in place.

## Getting help

If you have worked through the steps above and the problem persists, see the platform-wide [Troubleshooting](../../platform/troubleshooting.md) guide. Then reach out through [Support](../../platform/support.md) with the relevant log excerpts and the time the issue occurred.

## Related

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