Troubleshooting

This section covers common deployment and configuration issues. In many cases, the fastest way to diagnose problems is to review System Health from the admin panel.

1) 500 Error After Upload

A 500 error is usually caused by permissions, missing environment configuration, or server PHP settings.

• Ensure storage and bootstrap/cache are writable.
• Confirm your server is running PHP 8.x.
• Check server error logs for the exact message (Apache/Nginx error log).
• Verify your .env file exists and contains valid configuration.
• Run php artisan config:clear then php artisan config:cache after editing .env.

If you are on shared hosting, confirm your application is served from the public directory (see Installation).

2) Blank Page or "Something Went Wrong"

• Make sure APP_ENV=production and APP_DEBUG=false on production.
• Review logs in storage/logs to see the real error message.
• Verify permissions on storage and bootstrap/cache.
• Confirm APP_URL is set correctly to your domain (https).

3) Assets / CSS / JS Not Loading

If the UI looks unstyled or JavaScript is not working, assets may not be built or cached correctly.

• Make sure the public/build directory exists on your server (Vite build output).
• If you upload from local, upload the built assets too.
• Clear caches: php artisan optimize:clear.

4) Storage / Uploads Not Working (Images / Proof Files)

If uploaded files do not appear or URLs are broken, the storage symlink may be missing.

• Run: php artisan storage:link
• Ensure storage/app/public is writable.

5) Installer Requirements Failing

The installer performs environment checks (PHP version, extensions, writable paths). If requirements fail:

• Enable required PHP extensions on your server.
• Increase PHP memory limit if your hosting is too restricted.
• Confirm storage and bootstrap/cache are writable.

6) Database Connection Error

• Verify database host, username, password, and database name.
• Confirm the database user has sufficient permissions.
• Make sure the database server is reachable from your hosting.

If the database credentials are correct but the error persists, review the database status from System Health.

7) Cron / Scheduled Tasks Not Running

If scheduled jobs are not working (demo resets, maintenance tasks, periodic actions), cron is usually not configured.

• Shared hosting: configure Laravel scheduler (recommended every 5 minutes).
• VPS: configure Laravel scheduler every minute.

See the full setup guide here: Cron & Queue.

8) Queue Jobs Not Processing (Emails / Notifications)

If emails or background tasks are not being processed, the queue worker is not running.

• Shared hosting: use a cron-based queue worker (every minute).
• VPS: run a persistent worker using Supervisor (recommended).
• Confirm your queue driver configuration matches your setup (sync/database/redis).

See Cron & Queue.

9) Emails Not Sending

• Confirm SMTP values are correct in the .env file.
• Send a test email from the Email Templates section.
• Check your SMTP provider credentials and restrictions (ports, authentication, limits).

See Post Installation and Email Templates.

10) Stripe Webhook Not Working

Stripe billing relies on webhooks. If billing updates are not reflected:

• Confirm the webhook URL is correct and accessible via HTTPS.
• Make sure your server can receive Stripe POST requests (no firewall blocking).
• Check Stripe webhook delivery logs in Stripe dashboard.
• Confirm the correct Webhook Secret (whsec_...) is saved in Paymery settings.
• Verify you created the webhook under the correct mode (Test vs Live).

See Stripe Configuration.

11) Plans Not Purchasable / Stripe Checkout Issues

• Make sure billing mode is set correctly (Stripe or Manual) in Settings.
• If Stripe is enabled, confirm each plan has a valid Stripe Price ID.
• Verify Stripe price currency matches the active site currency.
• If you recently changed .env, clear caches: php artisan optimize:clear.

See Plans and Stripe Configuration.

12) Still Stuck?

Start with System Health and check the section that matches your issue (Database/Cache, Mail, Queue, Billing, Storage). In most cases, the missing configuration will be highlighted there.