Troubleshooting

Solutions to the most common issues. Most problems come down to queue workers, the scheduler, webhooks or caches.

Background jobs aren't running

Symptoms: campaigns stuck, inbound messages not appearing, emails not sending, AI not replying.

Fix:

  • Ensure QUEUE_CONNECTION is database or redis (not sync).
  • Run a queue worker that covers all queues:
    php artisan queue:work --queue=whatsapp,broadcast,ai,social,leads,automation,default
  • In production, supervise it (Supervisor/systemd) — see Deployment.
  • Check Admin → Queue for failed jobs and read the exception message.

Scheduled things don't happen

Symptoms: scheduled campaigns don't send, renewals don't reconcile, trials don't expire.

Fix:

  • Add the cron entry:
    * * * * * cd /path/to/app && php artisan schedule:run >> /dev/null 2>&1
  • Confirm the heartbeat is green in Admin → Cron Setup.

Emails aren't being delivered

Fix:

  • MAIL_MAILER must not be log. Configure SMTP in Admin → Email System (or .env).
  • Send a test email from Admin → Email System.
  • Set up SPF/DKIM/DMARC on your sending domain for deliverability.
  • Make sure the queue worker is running (emails are queued).

WhatsApp/Meta messages not arriving

Fix:

  • APP_URL must be a public HTTPS domain.
  • The Meta App integration must be enabled with App ID + App Secret in Admin → Integrations.
  • Confirm the webhook is registered in the Meta dashboard (embedded signup does this automatically; customers can Re-register webhook).
  • Run the queue worker including the whatsapp queue.
  • For Instagram/Messenger, confirm the instagram/page objects are subscribed to messages.

Subscription renewals not working

Fix:

  • Register the webhook endpoint in the gateway dashboard (/webhooks/stripe|paypal|paddle).
  • Store the signing secret — in production a missing secret rejects all webhooks (401).
  • Subscribe to the correct events (see Payments).
  • Ensure the queue worker and scheduler are running (billing:sync self-heals hourly).

Real-time / live updates not working

Fix:

  • Set BROADCAST_CONNECTION to pusher or reverb.
  • Enter Pusher credentials in Admin → Real-time Settings and click Test.
  • For Reverb, ensure the Reverb server process is running and proxied.
  • The app still works without real-time — users just need to refresh.

Translations look "missing" after editing JSON

Fix: The dictionary is cached. Edit translations via Admin → Languages (which refreshes automatically), or clear the cache after manual JSON edits. See i18n.

Changes to .env don't take effect

Fix: Clear (and in production, re-cache) the config:

php artisan config:clear
php artisan config:cache

500 errors / blank pages after deploy

Fix:

  • Run php artisan optimize:clear, then re-cache.
  • Ensure storage/ and bootstrap/cache/ are writable by the web user.
  • Rebuild assets: npm run build.
  • Temporarily set APP_DEBUG=true to read the error (revert to false after).
  • Check storage/logs/laravel.log (or enable Sentry).

File uploads fail or disappear

Fix: Check storage/ permissions, or move to cloud Storage (S3/Spaces/Wasabi) — especially on ephemeral hosting.

Customers can't do anything / everything is blocked

Fix: Demo mode may be on. Set APP_DEMO_MODE=false and clear config. See Demo Mode.

Still stuck?

Gather the relevant log lines (storage/logs/laravel.log), the failed-job exception (Admin → Queue), and the steps to reproduce, then contact support.

Last Updated: