Troubleshooting

Common issues, their causes, and step-by-step solutions. Plus essential artisan commands for maintenance and diagnostics.

Common Issues

ProblemCauseSolution
Blank/white page Build not compiled or PHP error Run npm run build and check storage/logs/laravel.log
Error 500 Missing .env key or misconfiguration Run php artisan config:clear and verify APP_KEY is set
Permission denied Wrong file ownership sudo chown -R www-data:www-data storage bootstrap/cache && sudo chmod -R 775 storage bootstrap/cache
Workflows don't execute Queue worker not running Start the worker: php artisan queue:work --queue=events,webhooks
Scheduled workflows don't trigger Cron not configured Add to crontab: * * * * * cd /path && php artisan schedule:run >> /dev/null 2>&1
Assets not loading (CSS/JS 404) Build not run or wrong document root Run npm run build and ensure server document root points to /public
Storage files 404 (logos/uploads) Missing storage symlink Run php artisan storage:link
Login redirect loop Session misconfigured Check SESSION_DRIVER=database in .env and verify the sessions table exists
Cache stale Config/routes cached with old values php artisan cache:clear && php artisan config:clear && php artisan route:clear && php artisan view:clear
Migration error Database connection issue Verify DB_* values in .env, test connection with php artisan db:show
Memory limit exceeded PHP memory too low Set memory_limit = 256M in php.ini
File upload fails PHP upload limits too low Set upload_max_filesize = 10M and post_max_size = 12M in php.ini
WhatsApp 24h window closed No customer message received in 24 hours Use an approved template message instead (configure fallback_template in WhatsApp settings)
AI budget exceeded Monthly token limit reached Increase the budget in Settings > Modules > AI
Email rate limited Hourly sending limit reached Wait for the hourly reset or increase rate_limit_per_hour in email settings
Webhook not received URL not reachable or signature mismatch Verify the URL is publicly accessible via HTTPS, and check the webhook secret matches

Artisan Maintenance Commands

Use these commands for routine maintenance and diagnostics:

bash 
# Clear application cache
php artisan cache:clear

# Cache configuration (production only)
php artisan config:cache

# Cache routes (production only)
php artisan route:cache

# Clear compiled views
php artisan view:clear

# Restart queue workers gracefully
php artisan queue:restart

# Create storage symlink
php artisan storage:link

# Run pending migrations
php artisan migrate --force

# List scheduled tasks
php artisan schedule:list

# Preview data cleanup (dry run)
php artisan cleanup:old-data --days=90 --dry-run

Diagnostic Steps

When encountering an issue, follow this general diagnostic workflow:

  1. Check the Laravel log: tail -f storage/logs/laravel.log
  2. Check the queue: php artisan queue:failed to see failed jobs
  3. Verify environment: php artisan env to confirm the current environment
  4. Test database: php artisan db:show to verify connection
  5. Clear all caches: Run the full cache clear sequence above
  6. Check permissions: Ensure storage/ and bootstrap/cache/ are writable
  7. Review server logs: Check Nginx/Apache error logs for HTTP-level errors

Production Caching

In production, always run php artisan config:cache and php artisan route:cache after making .env or route changes. Cached configs will not pick up .env changes until you re-cache.

Getting Help

If the issue persists after following the steps above: