Skip to main content

Failed Jobs

View and manage failed job processes within the system, allowing you to diagnose issues and reattempt failed tasks to ensure proper execution. Mumara uses Laravel's queue system to process time-consuming tasks in the background, such as sending emails, processing imports, generating exports, and calculating statistics. When a background job encounters an error and cannot complete successfully, it gets recorded in the Failed Jobs log for review and potential retry.

Navigate to Tools → Logs → Failed Jobs to access the failed jobs manager.

Understanding Background Jobs​

Mumara offloads many operations to background queues to keep the web interface responsive. Instead of making you wait while the system processes thousands of emails or imports a large contact file, these tasks run in the background via queue workers. This allows you to continue working while heavy processing happens behind the scenes.

How Jobs Fail​

A background job can fail for several reasons:

Failure TypeDescription
Max attempts exceededThe job was attempted multiple times but kept failing - after reaching the maximum retry limit, it's marked as permanently failed and moved to the failed jobs table
TimeoutThe job took longer than the allowed execution time - this often happens with very large data sets or slow external services
Exception thrownThe job encountered an unhandled error during execution - the exception message and stack trace are captured for debugging
Memory exhaustedThe job required more memory than PHP was configured to allow - common with large imports or exports
External service failureThe job depends on an external service (SMTP server, API, etc.) that was unavailable or returned an error
Database connection lostThe database connection was interrupted during job execution - often due to timeouts or server restarts
Invalid dataThe job payload contained data that couldn't be processed - such as malformed email addresses or corrupted import files

Common Job Types in Mumara​

Background jobs in Mumara handle various operations throughout the application:

Job CategoryExamples
Email deliverySending broadcast campaigns, drip emails, trigger-based messages, and transactional notifications
Contact importsProcessing uploaded CSV files, parsing contact data, and inserting records into lists
Data exportsGenerating downloadable files for contact exports, statistics reports, and log archives
Statistics processingCalculating campaign metrics, aggregating open/click data, and updating dashboard analytics
Bounce processingParsing bounce emails, updating contact statuses, and processing feedback loop reports
Webhook processingHandling incoming callbacks from ESPs, payment providers, and integrated services
Scheduled tasksRunning evergreen campaigns, executing triggers, and performing automated maintenance

Working with Failed Jobs​

Reviewing Failures​

When a job fails, the system captures diagnostic information to help you understand what went wrong:

  • Connection and Queue - Identifies which queue worker and queue name processed the job, helping pinpoint infrastructure issues
  • Exception details - The error message and stack trace showing exactly where and why the job failed
  • Failure timestamp - When the job failed, useful for correlating with other system events or outages

Retrying Failed Jobs​

Many job failures are temporary - a momentary network issue, a briefly unavailable service, or a race condition. Once you've identified and resolved the underlying issue, you can retry failed jobs to complete the originally intended operation.

Before retrying:

  1. Review the exception to understand why the job failed
  2. Check if the issue is resolved - retrying without fixing the problem will just create another failure
  3. Consider the impact - some jobs may no longer be relevant (like sending a time-sensitive email days later)

Deleting Failed Jobs​

Remove failed jobs when:

  • The underlying issue has been resolved and the job is no longer needed
  • The job is no longer relevant (outdated notification, expired campaign, etc.)
  • You've manually completed the task the job was supposed to perform
  • The failure was due to intentionally removed data (deleted contacts, removed lists, etc.)

Troubleshooting Common Failures​

MaxAttemptsExceededException​

This exception indicates the job kept failing and exhausted its retry attempts:

Possible causes:

  • Persistent external service outage
  • Recurring database connectivity issues
  • Systematic data problems affecting all retry attempts

Solutions:

  • Check external service status and connectivity
  • Review database server health and connection limits
  • Examine the job payload for data issues
  • Once resolved, retry the job

Memory Exhaustion​

Jobs that process large data sets may run out of memory:

Possible causes:

  • Importing very large contact files
  • Generating exports with too many records
  • Processing campaigns with huge recipient lists

Solutions:

  • Increase PHP memory_limit in php.ini
  • Break large operations into smaller batches
  • Optimize server resources for queue workers

Timeout Failures​

Jobs that take too long get terminated:

Possible causes:

  • Slow external API responses
  • Database queries taking too long
  • Processing unusually large data sets

Solutions:

  • Increase queue job timeout settings
  • Optimize slow database queries
  • Check external service performance
  • Consider breaking large jobs into smaller chunks

Connection Failures​

Jobs that can't reach required services:

Possible causes:

  • SMTP server unreachable
  • Database server connection issues
  • External API endpoints down
  • Network or firewall problems

Solutions:

  • Verify service availability
  • Check network connectivity from the server
  • Review firewall rules
  • Confirm credentials and connection settings

Best Practices​

Regular Monitoring​

  • Check failed jobs daily - don't let failures accumulate unnoticed as they may indicate systematic problems
  • Set up alerts - configure notifications for job failures so you're aware of issues immediately
  • Watch for patterns - multiple jobs failing with similar errors often indicate an infrastructure or configuration problem

Preventive Measures​

  • Ensure queue workers are running - failed jobs can't be processed if workers aren't active; check Cron Status regularly
  • Monitor server resources - adequate memory, CPU, and disk space help prevent resource-related failures
  • Keep services healthy - ensure SMTP servers, databases, and external APIs are performing well
  • Test configuration changes - verify that settings changes don't break background job processing

Cleanup and Maintenance​

  • Remove resolved failures - once you've addressed the issue and no longer need the job, delete it to keep the list manageable
  • Don't ignore old failures - accumulated failed jobs may indicate ongoing issues or represent lost data/operations
  • Document recurring issues - if certain job types fail frequently, investigate the root cause rather than just retrying

Next Steps​

Last updated on