What are email notifications for failed background jobs in Frappe?
Email notifications for failed background jobs allow Frappe Framework v15 to automatically alert system administrators when a background worker crashes or a queued task fails unexpectedly.
This feature is critical for production ERPNext systems, where silent job failures can cause data inconsistencies, stuck processes, or delayed automation.
Why Failed Background Job Alerts Are Important
Background jobs in Frappe Framework handle:
- Scheduled tasks
- Email sending
- Stock updates
- Long-running automation
- Integration callbacks
Without alerts, failures may go unnoticed until business operations are affected.
How Frappe Handles Background Job Failures
When a background job fails in Frappe v15:
- The job is marked as failed in Redis queue
- The traceback is logged
- Failure metadata is stored
- Optional email notification is triggered (if enabled)
This mechanism relies on server configuration, not application code.
Configuration & Setup
How to Enable Email Notifications for Failed Background Jobs
Direct Answer:
You must configure the background_job_failure_emails setting at the site level.
Step-by-Step Configuration
Open the site configuration file:
sites/[your-site-name]/site_config.json
1. Add the following key:
{
"background_job_failure_emails": [
"admin@example.com",
"devops@example.com"
]
}
2. Save the file.
3. Restart background workers and services.
How the Notification System Works
Once enabled:
- Any unhandled exception in a background job
- Or a worker crash
Will trigger an email containing:
- Site name
- Queue name
- Job name
- Exception traceback
This behavior is implemented internally in Frappe’s background job handling logic and does not require custom hooks.
Email Prerequisites
To ensure alerts are delivered:
- Outgoing Email Account must be configured
- SMTP credentials must be valid
- Background workers must be running
If email is misconfigured, failures will still be logged but emails will not be sent.
User Guidance: When Should You Enable This?
Enable failed background job emails when:
- Running ERPNext in production
- Using integrations or scheduled jobs
- Handling financial, inventory, or compliance data
- Operating multi-site environments
For development systems, this setting is optional.
Best Practices & Tips
- Use distribution lists, not personal emails
- Separate alerts for staging and production
- Monitor Redis queue health alongside emails
- Combine with server-level logging and uptime alerts
Advanced Topic: Multi-Site Monitoring
In multi-tenant setups:
- Configure background_job_failure_emails per site
- Use a centralized mailbox for alert aggregation
- Correlate failures with queue (short, long, default)
This ensures faster root-cause analysis.
Troubleshooting Common Issues
Emails not received
- Verify SMTP configuration
- Check spam/junk folder
- Confirm workers are restarted
Too many alerts
- Investigate recurring job failures
- Review custom background tasks
- Fix retry loops or failing integrations
Technical Categories
- Frappe Modules: Background Jobs, Email
- Technical Terms: Redis Queue, Worker, Background Job
- Tags: ERPNext Customization, Frappe Framework Tutorial
Target Audience
- ERPNext system administrators
- DevOps engineers
- ERP implementation partners
- SaaS operators using Frappe v15
Summary
Email notifications for failed background jobs in Frappe Framework v15 provide a simple yet powerful production monitoring layer. By enabling a single configuration key, teams gain immediate visibility into job failures—preventing silent data issues and improving system reliability.
