Weave Code
Laravel Failed Job Monitor Laravel Package
spatie/laravel-failed-job-monitor
Spatie's Laravel Failed Job Monitor sends notifications when a queued job fails. It uses Laravel's native notification system and can alert via mail or Slack, with configuration for enabled status, channels, email addresses, and Slack webhook URL.
spatie/laravel-failed-job-monitor sends notifications whenever a queued job fails, so problems in your queue don't go unnoticed. It hooks into Laravel's native notification system, letting you alert the right people through mail or Slack with minimal setup.
Install it via Composer, publish the config file, and add a few environment variables to control whether monitoring is enabled, which channels to use, and where alerts should go. A default notifiable is configured for you, but you can swap in your own.
- Out-of-the-box mail and Slack notifications
- Built on Laravel's native notification system
- Simple
.env-based configuration (FAILED_JOB_CHANNELS,FAILED_JOB_EMAILS, etc.) - Customizable notifiable and channel routing
- Auto-registered service provider with publishable config
Frequently asked questions about Laravel Failed Job Monitor
- How do I install and set up spatie/laravel-failed-job-monitor in a Laravel app?
- Run composer require spatie/laravel-failed-job-monitor; the service provider is auto-discovered. Publish the config with php artisan vendor:publish --tag=failed-job-monitor-config, then add FAILED_JOB_MONITOR_ENABLED, FAILED_JOB_CHANNELS, FAILED_JOB_EMAILS and FAILED_JOB_SLACK_WEBHOOK_URL to your .env file. If you plan to use Slack, also install guzzlehttp/guzzle, because the Slack channel needs an HTTP client at notification time.
- Which queue drivers does this failed job monitor work with?
- It hooks Laravel's job failed event and dispatches a native notification, so it has no coupling to any queue backend. It works the same with database, Redis, SQS or Horizon-managed Redis queues, and it adds no tables, sidecars or infrastructure. It is a notifier only: it sends one notification per failed job and does not aggregate failures or track failure rates.
- How do I configure mail and Slack alerts for failed jobs using environment variables?
- Set FAILED_JOB_MONITOR_ENABLED=true, FAILED_JOB_CHANNELS=mail,slack, FAILED_JOB_EMAILS and FAILED_JOB_SLACK_WEBHOOK_URL in your .env. The default notifiable reads those values from the published config file, so you can also point it at your own notifiable class. Keep the channel list comma-separated without spaces.
- Why is one of my FAILED_JOB_CHANNELS silently skipped?
- The package parses FAILED_JOB_CHANNELS with explode(',', env(...)) and does not trim whitespace, so mail, slack produces a channel name of ' slack' that is silently skipped. Write the list as mail,slack with no spaces. This is a common cause of notifications that look configured but never arrive.
- Why does a closure in notificationFilter cause configuration files are not serializable?
- Laravel's config:cache serializes configuration files, and a Closure cannot be serialized, so it throws LogicException: Your configuration files are not serializable. Replace the closure with a static class-method callable such as [App\Support\JobFilters::class, 'shouldNotify'] and it will cache cleanly. Most production pipelines run config:cache, so use a static callable from day one.
- How do I send failed job notifications to Microsoft Teams, Opsgenie or a custom webhook?
- Because notifications go through Laravel's native notification system, you can swap the notification class and notifiable in the config for your own. A custom notification can target Teams, Opsgenie, SMS or a generic webhook using any Laravel notification channel without forking the package. This is the lever to use if your organisation standardises on a specific incident platform.
- Does it deduplicate or rate limit notifications when hundreds of jobs fail at once?
- No. The package sends one notification per failed job and has no deduplication, aggregation or rate limiting. A systemic outage such as a database or third-party API failure can fail hundreds of jobs and flood mail or a Slack webhook, which is why Slack throttles around one message per second per hook. Pair it with Horizon alerts or Sentry/Bugsnag style tooling rather than relying on it alone.
- Can it alert me when a queue worker stalls or the queue stops processing entirely?
- No, the trigger is strictly a failed job. A stalled worker, a dead consumer, a misconfigured scheduler or a full failed_jobs table produces no notification, so the absence of alerts does not prove the queue is healthy. Use a heartbeat or dead-man's switch monitor alongside it if you need to detect a queue that stopped processing.
- How do I test failed job notifications and roll them out safely to production?
- Add the env variables in staging first and dispatch an intentionally failing job to confirm delivery end to end, including that guzzlehttp/guzzle is installed if Slack is a channel. Run php artisan config:cache after configuring a static notification filter to catch serialization problems before deploy. In production, FAILED_JOB_MONITOR_ENABLED gives you a runtime kill switch for a clean rollback.
- What Laravel versions are supported and is the package still maintained?
- Current releases support modern Laravel versions, while v3.x is the line to use for Laravel 5.8 and 6.x; check Packagist for the exact constraint for your version. The package is maintained by Spatie and is a leaf dependency with no dependents, so it cannot create transitive version conflicts for your app. Notification exceptions inside the failure path are worth verifying in staging, since delivery failures happen while the queue is already degraded.
Weaver
How can I help you explore Laravel packages today?