Troubleshooting

This page covers common issues and practical fixes when running SaasForgeKit.

First place to check: logs

Laravel application logs:

storage/logs/laravel.log

For most 500 errors, logs will reveal the root cause immediately.

Common issues

1) 500 error or blank page

Checklist:

• Verify .env values (APP_KEY, APP_URL, DB_*, MAIL_*).
• Clear caches:
  • php artisan optimize:clear
• Confirm write permissions for:
  • storage/
  • bootstrap/cache/
• Run pending migrations:
  • php artisan migrate --force

2) Vite manifest not found / assets missing

If styles/scripts are missing in production:

• Install/build frontend assets:
  • npm install
  • npm run build
• Confirm public/build/manifest.json exists.
• On shared hosting, verify public path setup (including bootstrap/app.php public path override when needed).

3) Stripe webhook events not updating app state

Checklist:

• Webhook URL points to /stripe/webhook.
• STRIPE_WEBHOOK_SECRET matches Stripe endpoint signing secret.
• Required events are enabled (Cashier defaults + app-specific events).
• Queue worker is running so follow-up jobs/emails process.

4) Social login button missing or provider unavailable

Checklist:

• Social auth is globally enabled in admin settings.
• Provider is enabled in admin settings.
• Provider env keys are present and valid.
• Redirect URI/callback URL matches exactly between provider console and app config.

5) Queue jobs not processing

Checklist:

• QUEUE_CONNECTION is configured correctly.
• Worker process is running in production.
• Failed jobs are monitored and retried when appropriate.

Still stuck?

• Reproduce in a clean environment if possible.
• Collect logs and exact reproduction steps.
• Contact support with detailed context (see Getting Support).