# Troubleshooting — MetaSoul ERP

Common install and runtime issues. Start from [INSTALL.md](INSTALL.md).

---

## HTTP 500 after deploy

1. Set `APP_DEBUG=true` **temporarily** on a private host only, or read `storage/logs/laravel.log`.  
2. Confirm `APP_KEY` is set (`php artisan key:generate`).  
3. Confirm `storage/` and `bootstrap/cache/` are writable.  
4. Run `php artisan migrate --force`.  
5. Clear caches: `php artisan optimize:clear`.  
6. For production, set **`APP_DEBUG=false`** again after fixing.

---

## Blank page / CSS missing (Vite assets)

Symptoms: unstyled HTML, missing JS, console 404 on `/build/assets/...`.

```bash
npm install
npm run build
```

Confirm `public/build/manifest.json` exists. Do not rely on `npm run dev` on a shared host.

If using a subdirectory, ensure `APP_URL` matches the browser URL.

---

## “Please provide a valid cache path” / view errors

```bash
php artisan view:clear
php artisan optimize:clear
```

Ensure `storage/framework/views` exists and is writable.

---

## Migrations slow or timeout

- Prefer MySQL for large seeds; SQLite full seed can be slow.  
- Raise PHP `max_execution_time` / `memory_limit` for CLI:

```bash
php -d memory_limit=512M -d max_execution_time=0 artisan migrate --seed
```

- Run migrate and seed separately if the host kills long requests.

---

## Full seed runs out of memory

```bash
php -d memory_limit=512M artisan db:seed-full
```

If `route:cache` OOMs:

```bash
php -d memory_limit=512M artisan route:cache
```

See [ROUTES.md](ROUTES.md) for workspace alias catch-alls and `WORKSPACE_ACTION_ALIASES`.
---

## Queue / mail not sending

1. Check `QUEUE_CONNECTION` (default `database`).  
2. Run a worker: `php artisan queue:work --tries=1`.  
3. With `MAIL_MAILER=log`, mail only appears in `storage/logs` — configure SMTP for real delivery.  
4. Failed jobs: `php artisan queue:failed`.

---

## Login works but `/app` redirects / 403

Portal-only users cannot open the workspace. Sign in with an **admin** or staff role account. See [ROLES.md](ROLES.md).

---

## Payments not marking paid

- Forged success URLs are ignored by design.  
- Stripe needs a real Checkout session + optional webhook — [PAYMENTS.md](PAYMENTS.md).  
- Demo provider requires Demo Mode confirmation.  
- Confirm `APP_URL` matches the return URL domain.

---

## Storage / upload links broken

```bash
php artisan storage:link
```

Confirm the symlink `public/storage` → `storage/app/public` exists.

---

## Wrong URL / mixed content / redirect loops

- Set `APP_URL` to the exact public base (https, host, path).  
- On HTTPS hosts, force HTTPS at the web server or via trusted proxy config.  
- Clear config cache after changing `.env`: `php artisan config:clear`.

---

## reCAPTCHA blocks login

Disable in Settings → Integrations, or set valid `RECAPTCHA_*` keys matching `RECAPTCHA_TYPE` (`v2` vs `v3`).

---

## PHPUnit / `composer test` memory

The default suite needs **768M–1024M** PHP memory (`composer.json` scripts pass `-d memory_limit=768M` or `1024M`). If tests exit with memory errors:

```bash
php -d memory_limit=1024M artisan test --compact
composer test:phase1
```

`composer test:phase1` is the buyer-critical subset (~185 tests) and is the recommended pre-upload check.

---

## Still stuck?

1. `php artisan about` — sanity check env/DB.  
2. Latest lines in `storage/logs/laravel.log`.  
3. Confirm PHP 8.3+ and required extensions.  
4. Re-read [CONFIGURATION.md](CONFIGURATION.md).

---

*Related: [UPDATE.md](UPDATE.md) · [BACKUP.md](BACKUP.md)*