Troubleshooting

Security / admin HTML content

Legal pages, blog posts, custom CSS, and blog head scripts are admin-controlled and can include HTML or JavaScript. This is expected for a CMS, but only trusted administrators should have access.

See Trusted admin content (XSS) for the security model and optional sanitization notes.

---

Installation

composer install fails

• Enable PHP extensions: openssl, pdo_mysql, mbstring, fileinfo.
• Increase memory_limit in php.ini.

npm run build fails

• Use Node 20+.
• Delete node_modules and lockfile, reinstall.
• Ensure 4 GB RAM for build on small VPS.

Migration errors

• Database user needs CREATE privileges.
• For MySQL, use utf8mb4_unicode_ci.

---

Frontend cannot reach API

Symptom

Network tab shows CORS error or Failed to fetch.

Fix

1. Set API_URL in frontend/.env to exact backend origin.
2. Set FRONTEND_URL and, if needed, CORS_ALLOWED_ORIGINS in backend .env.
3. Set supports_credentials => true (default).
4. php artisan config:clear

---

---

419 CSRF token mismatch on sign-in

Symptom

POST /api/auth/signin returns 419 with "CSRF token mismatch." CORS headers may look correct (access-control-allow-origin is set).

Direct browser access to GET /api/settings/general works, but the same URL from the Nuxt site fails before login is attempted.

Cause

The API and frontend are on different subdomains (e.g. api-exchangepro.xorinlab.com and exchangepro.xorinlab.com) but SESSION_DOMAIN is not set. Session and CSRF cookies are scoped to the API host only, so the frontend cannot sync the X-XSRF-TOKEN header with the session.

Fix

1. Set in backend/.env:

   APP_URL=https://api-exchangepro.xorinlab.com
   FRONTEND_URL=https://exchangepro.xorinlab.com
   SESSION_DOMAIN=.xorinlab.com
   SESSION_SECURE_COOKIE=true
   SESSION_SAME_SITE=lax

2. Run php artisan config:clear && php artisan config:cache.

3. Clear browser cookies for your domain (or use a private window).

4. Confirm GET /sanctum/csrf-cookie runs before POST /api/auth/signin in the Network tab.

See CORS & Sanctum → Session cookies.

---

Missing APP_KEY (500 on SPA requests)

Symptom

API returns 500 from the frontend with MissingAppKeyException: No application encryption key has been specified. Opening the same URL directly in the browser tab may still work.

Fix

cd backend
php artisan key:generate
php artisan config:cache

Ensure APP_KEY=base64:... is present in .env on the server (.env is not deployed via git).

---

Login fails / session not persisted

Symptom

Sign-in appears successful but next request is 401.

Fix

1. CORS & Sanctum - SESSION_DOMAIN for subdomains.
2. Use HTTPS in production with SESSION_SECURE_COOKIE=true.
3. Check browser blocks third-party cookies (prefer same root domain for API + frontend).
4. Confirm sanctum/csrf-cookie returns 204 before signin.
5. Run php artisan config:cache after any .env change.

---

Admin API 403

Symptom

Admin UI loads but API calls to /api/admin/* return 403 or 401.

Causes

• User is not role = admin (check users.role in the database).
• Session expired - sign out and sign in again.
• CORS or Sanctum stateful domain misconfiguration (login works but API calls fail).

Fix

• Promote user in database: users.role = 'admin'.
• Clear cookies and re-login.
• Check Laravel log at storage/logs/laravel.log.

---

Password reset link wrong host

Symptom

Email links point to localhost.

Fix

Set backend FRONTEND_URL to production Nuxt URL and php artisan config:clear.

---

OAuth redirect_uri_mismatch

Redirect URI in Google/Facebook console must exactly match:

{APP_URL}/api/auth/google/callback

APP_URL must include scheme (https://) and no trailing slash.

---

Proof upload fails

Symptom	Fix
413 Request Entity Too Large	Increase Nginx client_max_body_size
422 validation	File over 5 MB or wrong field
Permission denied	Writable public/transaction-proofs/

---

Rate sync not running

1. Enable API in admin settings with valid key.
2. Add cron: * * * * * php artisan schedule:run.
3. Run php artisan schedule:list to confirm hourly task.

---

Mail not sending

See Mail configuration. Test with MAIL_MAILER=log first.

---

Blank home page / missing content

• Run migrations (home page seed migration).
• Check GET /api/settings/home-page or public settings endpoint.
• Configure home page in admin.

---

500 error after deploy

php artisan config:clear
php artisan cache:clear
chmod -R 775 storage bootstrap/cache

Check storage/logs/laravel.log for stack trace.

---

Enable debug temporarily

Development only:

APP_DEBUG=true

Never leave enabled on production - exposes sensitive paths and data.

---

Still stuck?

Collect before contacting support:

1. PHP version (php -v)
2. Node version (node -v)
3. Relevant .env keys (redact secrets)
4. Browser console + Network tab output (F12)
5. Last 50 lines of laravel.log