Pular para o conteúdo principal

🐛 Common Issues

Solutions to the most common issues encountered with Monitron SaaS.

🔴 Installation Issues​

Blank white page after install​

# Check permissions
sudo chown -R www-data:www-data /var/www/monitron
sudo chmod -R 775 storage/ bootstrap/cache/

# Check the log
tail -50 storage/logs/laravel.log

# Clear caches
php artisan config:clear
php artisan cache:clear
php artisan view:clear

"500 Server Error" on first visit​

Usually a missing .env or APP_KEY:

cp .env.example .env
php artisan key:generate

"Class not found" errors​

composer install --no-dev --optimize-autoloader
php artisan optimize

Installation wizard not showing​

  • Verify web server points to public/ directory
  • Check that storage/installed.lock doesn't exist yet
  • Verify .env file exists

🟡 Monitoring Issues​

Monitors stuck on "Pending"​

Queue workers aren't running:

# Check worker status
sudo supervisorctl status

# Start workers manually (for testing)
php artisan queue:work --once

# Check for failed jobs
php artisan queue:failed

Monitors not checking​

The scheduler (cron) isn't running:

# Verify cron entry exists
crontab -l

# Run manually to test
php artisan schedule:run

# Check if scheduler tasks are registered
php artisan schedule:list

HTTP monitor always shows "down" but site works​

  • Self-signed SSL? Disable "Verify SSL" in the monitor config
  • Firewall blocking? Make sure the Monitron server can reach the target
  • CDN blocking? Some CDNs block automated requests — add a custom User-Agent header
  • Expected status code wrong? Check if the site returns 301 instead of 200

Response times are very high​

  • DNS resolution slow? Try using the IP address instead of hostname
  • Distant server? Latency is expected for geographically distant checks
  • Check interval too fast? Reduce frequency if the target is rate-limited

🔴 Notification Issues​

No notifications being sent​

  1. Check queue workers are running: supervisorctl status
  2. Check notification logs: Admin → Notification Logs
  3. Check email settings: Admin → Settings → Email
  4. Check contacts have channels configured

Slack/Discord webhook errors​

  • Webhook URL expired? Recreate it in Slack/Discord
  • Channel deleted? The webhook becomes invalid

Telegram "chat not found"​

  • Did you start a conversation with the bot first?
  • Is the chat ID correct? (Group IDs start with -)
  • Bot removed from the group?

🟡 Performance Issues​

Dashboard is slow​

# Optimize Laravel
php artisan optimize
php artisan view:cache
php artisan config:cache
php artisan route:cache

# Check database indices
php artisan migrate:status

Database growing too large​

Reduce data retention:

  • Admin → Settings → General → Data Retention Days
  • Or purge manually:
php artisan tinker
>>> MonitorCheck::where('checked_at', '<', now()->subDays(30))->delete();

Queue workers consuming too much memory​

# Add --max-jobs and --max-time to worker config
command=php /var/www/monitron/artisan queue:work --sleep=3 --tries=3 --max-time=3600 --max-jobs=1000

🔴 Upgrade Issues​

"Migration failed" after upgrade​

# Check current migration status
php artisan migrate:status

# Try running specific migration
php artisan migrate --force

# Check the log for SQL errors
tail -50 storage/logs/laravel.log

"Class not found" after upgrade​

composer install --no-dev --optimize-autoloader
php artisan package:discover

Styles broken after upgrade​

php artisan filament:optimize
php artisan view:clear
# Hard-refresh browser: Ctrl+Shift+R