Skip to main content

๐Ÿ› 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