Troubleshoot notifications in Jira
JIRA applications have a very flexible built-in facility for sending out email notifications under a wide variety of conditions. This guide is meant to help troubleshoot when email notifications are not being received.
There is now a Notification Helper plugin - please check the notifications with this plugin prior to following these instructions.
No email notifications are being received by anyone
- Ensure you've properly configured an SMTP Server. Send a Test Mail inside the SMTP Server configuration setup screen. Make a note of any error that is returned from the test.
- Check your JIRA application log files and the application server log files for Out of Memory errors. Typically, the log file will show java.lang.OutOfMemoryError: Java heap space. This has been known to cause the service responsible for sending emails out to fail until JIRA applications are restarted. You should further troubleshoot your memory issues using this guide.
- Check and ensure the Mail Queue Service is installed. Click Administration > Services to inspect that the service exists, and is set at a reasonable interval. This interval controls how frequently the mail queue is processed. You can flush the mail queue to send out pending messages immediately to your mail server.
- Inspect your Mail Queue under Administration > Mail Queue. See if you are given the option to Bypass currently sending mail. A stuck email or trackback ping can hold up the queue.
- Check that your Base URL is set to a domain / IP which your SMTP server will accept. Example: Google apps accounts must have a matching base URL to their Google Apps domain.
Enable additional logging in Administration > System > Troubleshooting and Support > Logging and Profiling by setting the following to
DEBUG to see more robust logging about services running at the background:
Email notifications are not being received by a specific group of people/person
- Check if the My Changes option in the user's profile is Notify Me. The default value for this property for all users can also be set under Administration > User Defaults
- Check the project permissions under the project's permission scheme. Users must have Browse Project permission for the project to which the issue belongs. If you're using Issue Security Levels, ensure they are members of any Issue security levels that have been applied to the issue.
A user may not have the necessary permission due to the fact that they have never logged into Jira, and as a result, they have not been assigned to any groups that have application access rights to Jira. These users could be sending an email to JIRA to create an issue rather than logging into JIRA but when the issue is updated, they do not receive email notification.
- Inspect the Mail Queue under Administration > Mail Queue and see if notifications are being queued. You can adjust the Mail Queue Service interval to a longer period for troubleshooting purposes. Inspect the Error Queue tab for any errors.
Notifications aren't occurring after clicking through a transition/workflow step
- Notifications are triggered in a transition by their post-function.
- Inspect the post-function of the transition step you're investigating and ensure it's firing an event.
- Inspect your notification scheme and check that the event Work Started On Issue actually has people mapped there.
- Ensure the notification scheme you just checked is actually assigned to your project.
The content of the email notification is wrong
- If the content of the notification refers to an invalid or non-existent issue, then the notification may be coming from another source. This situation can happen when you restore an XML backup of your production JIRA application instance into a development/test server. The development/test JIRA server application then begins sending out notifications in addition to your production instance. Please see this guide on Disabling email sending/receiving for a Development/Test JIRA instance.
- If users are receiving messages in HTML or Text and they wish to change this preference, have them change this property in their user profile under Outgoing email format.
- If the URL links inside the content of the notification point to the wrong site, check your base URL property under Administration > General Configuration.
- If the FROM: header of the mail being received is not what you've configured under Administration > General Configuration > Email from, check to see if the Project's Mail Project setting is set. It will override the global setting.
Issues created from e-mail do not generate notifications
- Please check your mail handler configuration and ensure that notifyusers is set in the handler parameters.
- Ensure that the User Preference for "Notify users of their own changes?" is set to YES in Administration > Users > User Preferences.
Comments created from e-mail do not generate notifications
- When JIRA applications process mail to add comments, if an attachment is included in the email it will fire an Issue Updated event instead of an Issue Commented event.
- Check to see if the Issue Updated event is notifying the expected recipients. If it is not, add those recipients to the notification scheme.
Duplicate notification emails are being sent from JIRA applications
- (JIRA 4.4.4+ only): Enable the Outgoing Mail log and the Incoming Mail Log in Administration > System > Troubleshooting and Support > Logging and Profiling.
Please ensure that the Debugging mode is ON
Remember to disable these once the problem is resolved as they can increase the overhead on server hosting, potentially cause degradation to performance and also consuming HDD space.
- (Pre JIRA 4.4.4): Set-Dmail.debug=true and restart JIRA.
- Check the
atlassian-jira.log(pre 4.4.4) to see if any SMTP timeouts are occurring, as in our Outbound mail fails to send in Jira server due to read timed out error KB article. JIRA applications may be successfully communicating with the mail server and sending the email and then timeouts while waiting for the response. As it does not receive a successful response from the SMTP, it will attempt to resend emails until it receives them.
- If you have any third-party mail plugins, please disable them and retest the behavior to see if the problem can be isolated further.
- Check if in addition to the seeded post-function from the "Create" transition, there is a third-party plugin which triggers the "Issue created" event. If that's the case, remove the "Issue Created" event trigger from the third-party app.
- Check whether you are watching the issue and one of the roles of the issue at the same time. You might need to check whether autowatch is currently turned on.
- Check the notification scheme to see if it contains a mailing list - if it uses a mailing list and another notification item such as Assignee, and the assignee is also within the mailing list, JIRA applications are not able to identify the users of the mailing list and will end up sending duplicate notifications.
Large mails are getting stuck in the mail queue.
- By default, JIRA applications have no limit on the size of text fields. This can mean enormous comments and descriptions can be constructed, causing performance problems and mail to fail to send.
- The jira.text.field.character.limit value can be set as per Configuring Advanced Settings, allowing the comment sizes to be limited. This can effectively workaround the problem.
Notifications are not sent for some issues
Review the Jira logs for errors related to image processing similar to:
java.lang.RuntimeException: org.apache.batik.transcoder.TranscoderException: null Enclosed Exception: null:0 The URI "data:image/png;base64,... on element <image> can't be opened because: PNG URL is corrupt or unsupported variant at org.apache.batik.transcoder.image.ImageTranscoder.transcode(ImageTranscoder.java:92) at org.apache.batik.transcoder.XMLAbstractTranscoder.transcode(XMLAbstractTranscoder.java:142) at org.apache.batik.transcoder.SVGAbstractTranscoder.transcode(SVGAbstractTranscoder.java:156) at com.atlassian.jira.avatar.AvatarTranscoderImpl.transcodeAndTag(AvatarTranscoderImpl.java:80) ... 55 more
This exception indicates Jira is having issues attach a custom priority icon to the email. We've seen this happen with malformed SVG files.
In this exception, the SVG data is contained in
xlink:href= which causes transcoding errors in the Apache Batik library.
Notifications for filter subscriptions are not sent
If you're using a custom priority icon and the priority column in visible in your filter, the same issue above may be occurring with filter subscription.
If your filter contains at least one issue with a malformed priority icon, no notifications will be sent for this filter.
General Troubleshooting Tips
- Reviewing your JIRA application logs will greatly help you narrow down the problem. Often, the problem exists in the mail server and a Google search of the error from the logs can help you identify the cause.
- The Mail Queue (under Administration > Mail Queue) can give you a general idea of how many emails are being generated.
- You can get more detailed logging under Administration -> System -> Logging & Profiling. Click Edit next to the com.atlassian package and change it from the WARN logging level to DEBUG. This change does not persist after a restart.
- For even more detailed logging (display the message headers, protocol details), see Logging email protocols.