Health Check: Mail Queue
About the health check
This health check ensures the healthiness of a mail queue. We consider a mail queue unhealthy if the oldest email it contains is stored there for at least the time specified by the threshold, which by default is 30 minutes. The value of the threshold can be overridden by using the mail.healthcheck.threshold.minutes
system property.
If you change the schedule of MailQueueService
to run less often than the threshold of the mail queue health check, you may see false positive health check failures.
In Jira Data Center, if you get a notification about a failed mail queue health check and see that the check passed on the System tools page, this might indicate failures on another node. In this situation, we highly recommend checking the mail queue on each node separately. This is a known issue and we’re working on improving the behavior of this health check and your experience with Jira.
Understanding the results
Jira Server
Icon | Result | What this means |
---|---|---|
Pass | Emails are sent without any issues. | The mail queue doesn't contain any emails that have been there for longer than the set threshold. |
Warning | Emails haven’t been sent from the mail queue for at least | The mail queue contains at least one email that has been there for longer than the set threshold. |
Jira Data Center
Icon | Result | What this means |
---|---|---|
Pass | Emails are sent without any issues on this node. If you got a notification about a failing mail queue health check, verify your other nodes. | The mail queue on this node doesn't contain any emails that have been there for longer than the set threshold. |
Warning | Emails haven’t been sent from the mail queue for at least | The mail queue on this node contains at least one email that has been there for longer than the set threshold. |
What happens if I ignore the warning?
If there’s at least one email that has been in the mail queue for longer than 30 minutes, and the default value of the mail queue service schedule wasn’t changed, your instance is most likely having trouble with sending emails regularly or isn’t sending them at all. This leads to delays in, for example, issue notifications or email communication between Jira and users.
Troubleshooting
WARN ServiceRunner [c.a.t.healthcheck.concurrent.SupportHealthCheckProcess] Health check 'Mail Error Queue' failed with severity 'warning': 'There are X emails in the error queue.'
Problem | Proposed solution |
---|---|
Emails haven’t been sent from the mail queue because the mail queue service did not recover from a temporary database connectivity issue. |
If the scheduling of the Mail Queue Service was stopped due to a connectivity issue with the database, performing the steps above should reset the scheduling of the service and it should run again. |
Emails haven’t been sent from the mail queue due to the mail queue service scheduling configuration. | Go to Administration > System > Services and check the cron value in the Schedule column of the Mail Queue Service. By default, the cron value should be set to the following value. This means that the service runs once a minute.
If the service is scheduled to be executed less often, try to schedule it to run every minute. |
Emails haven’t been sent from the mail queue because the outgoing mail server is configured with an infinite timeout value. |
If it’s set to 0, then it’s possible that the Mail Queue Service is stuck and is indefinitely waiting to get a connection from the SMTP server. If that’s the case, follow the steps below:
The action of restarting Jira will delete all the emails waiting in the mail queue, so it’s important to flush the queue before that.
|
For more information on the most common issues with the mail queue, check out this Knowledge base article.
Immediate mitigation step
As an immediate mitigation step, you might consider flushing the mail queue. To do so, go to Administration > System > Mail queue. This action will bypass the scheduling of the mail queue service and will try to send all mail in the queue immediately.
This action should only be executed as a temporary workaround since it won't resolve the mail queue issue permanently.
In some situations, manually flushing the mail queue won't help, and emails might still pile up in the queue. In such cases, don't try to flush the mail queue several times, as this action will generate more threads to be processed by the Jira application and cause potential performance issues.
Providing data to Atlassian Support
If you still can't troubleshoot and fix the problem, create a support ticket at support.atlassian.com and attach the requested information to the ticket by following the steps below:
Go to Administration > System > Logging and profiling.
In the Outgoing mail section, select Enable.
Select Enable debugging.
Select Configure logging level for another package.
Use com.atlassian.jira.service as the package name and select "DEBUG" for the Logging level.
Wait for about 15 minutes so that we can collect enough logs.
Go to Administration > System > Troubleshooting and support tools > Create support zip.
Select Customize zip, then select Thread dumps, and select Save.
Select Create zip and download the support zip. In case you have a Data Center cluster, repeat this step for each node.
Take screenshots of the following pages:
The Administration > System > Outgoing mail page after you select Edit.
The Administration > System > Mail queue page.
Run the following SQL query on the Jira database:
select * from rundetails where job_id = 'com.atlassian.jira.service.JiraService:10000';
Attach to the support ticket:
The screenshots.
The support zips.
The result of the SQL query.