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

---

Login fails / session not persisted

Symptom

Sign-in appears successful but next request is 401.

Fix

1. CORS & Sanctum — stateful domains.
2. Use HTTPS in production.
3. Check browser blocks third-party cookies (use same registrable domain when possible).
4. Confirm sanctum/csrf-cookie returns 204 before signin.

---

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