Jira Cloud Troubleshooting Guide
Learn to troubleshoot issues with the Jira Cloud integration.
Step 1: Pre-Checks
IP Safelisting Requirements
Before starting the troubleshooting process, please safelist the required PagerDuty IP addresses:
Step 2: General Troubleshooting
In PagerDuty
-
Check the Jira Cloud Configurations in PagerDuty: Navigate to Integrations Your Integrations Jira Cloud. Verify if there is a configuration connecting the PagerDuty service to the Jira project and issue type.
-
Note the Jira Issue Type: Check if the configuration correctly associates with the affected Jira issue type. Each configuration associates to a specific issue type - for example, if a configuration associates to the type Task, then its configuration rules will not apply to other issue types, such as Bug.
-
Check the Creation Type: Navigate to the configuration rule and review the option selected in the Creation Type field. Confirm if the option selected matches the expected issue creation behavior. In Automatic mode, PagerDuty will automatically create a Jira issue in the associated project. Manual mode will require responders to generate a Jira issue from the incident page (navigate to the More drop-down menu Create Jira Issue).
-
Review incident status mapping: Review the PagerDuty incident status to Jira issue status mappings, to confirm that the PagerDuty statuses are mapped correctly to the expected Jira issue status.
-
Complete the priority mapping section: If you enabled priorities for your PagerDuty account, complete the priority mapping section to map PagerDuty incident priorities to Jira issue priorities.
-
Some Jira issue fields may be required: Confirm which Jira issue fields are required for that Jira project and issue type. In the Jira Field mapping section, there must be a PagerDuty field mapped to each of the required Jira fields. Required fields are indicated with an asterisk:
In Jira Cloud
-
Workflow mapping: The issue workflow for the Jira project should contain a transition that would allow the issue to change from its current status to the desired status.
If the issue persists after completing these general troubleshooting steps, please refer to the following section for more specific troubleshooting steps.
Step 3: Troubleshooting Some Common Jira Cloud Issues
PagerDuty Incident did not Create a Jira Issue
In PagerDuty:
-
On the Jira Cloud Integration page, there should be a configuration linking the PagerDuty service to the Jira project and issue type.
-
Confirm if the option selected in the Creation Type field matches the expected issue creation behavior. If you’ve selected the manual issue mode, the responder must manually create a Jira issue from the More drop-down menu on the incident page.
In Jira:
-
Check if there are any conflicting automation rules configured to process incoming webhooks, or handle automatic issue creation.
-
Navigate to the project settings and check the valid issue types for this project.
-
Mapping a PagerDuty field to an incompatible Jira issue field may also prevent Jira issue creation. Check that the PagerDuty fields mapped to each Jira field match the data type expected for that field.
Jira Issue did not Trigger a PagerDuty Incident
In PagerDuty:
-
Navigate to the configuration rule in PagerDuty, and copy the JQL statement. In Jira, verify if that JQL statement returns the Jira issue in the results.
-
If Jira issues matching the JQL statement should trigger a PagerDuty incident, the Create an incident if the issue matches the JQL statement setting should be enabled.
-
The Jira project and Jira issue type are automatically appended to the JQL filter, according to the project and issue type selected in the configuration rule. At this time, the JQL filter cannot match other projects or issue types not selected in the configuration rule.
In Jira:
- Confirm if the issue matches the project and issue type defined in the configuration.
- If Jira issues should not automatically trigger a PagerDuty incident, then responders should manually trigger incidents from the PagerDuty widget in the issue sidebar.
PagerDuty Incident Status and Jira Issue Status did not Sync
In PagerDuty:
- On the incident page, confirm if the Jira issue is linked to the PagerDuty incident. The Jira issue must be linked to the incident in order to sync the incident record between the two platforms.
- In the configuration rule, there should be a mapping between the PagerDuty incident status and the desired Jira issue status.
Note: Jira cannot change the state of a PagerDuty incident to "Acknowledged". This ensures only PagerDuty users can acknowledge an incident is being worked on.
In Jira:
- Check if there is a workflow transition for that project and issue type, which would allow the issue to transition from the current status to the desired status.
- Confirm if any automations are transitioning the Jira issue to a different status than the one you expected.
- The PagerDuty application cannot transition issues to or from statuses that are not mapped in the configuration rule. To review the issue’s status change history, navigate to the issue’s Activity tab and look for updates indicating a status change.
PagerDuty Incident Fields and Jira Issue Fields did not Sync
In PagerDuty:
- In the configuration rule, there should be a mapping between a PagerDuty field and the Jira issue field. Check the mapping to confirm that the correct PagerDuty field is being mapped to that Jira issue field.
- The mapped fields are synced the moment the Jira issue is created - Jira fields do not get updated/synced after this point.
In Jira:
- Navigate to the project settings to verify if the field is available for that issue type. The Jira field data type should correspond with the PagerDuty field data type.
- Check if there are any conflicting global or project automations that also populate this issue field.
- The issue field must be placed on a screen that is mapped to the create issue operation via a screen scheme. The screen scheme must be mapped to the issue type via a issue type screen scheme that is associated to the Jira project.
A Jira Ticket is Triggering Multiple PagerDuty Incidents
In PagerDuty:
- In the configuration rule, the JQL statement for automatically triggering a PagerDuty incident should include an Open/To-Do status (as defined by your company) so that a PagerDuty incident is only triggered when the issue is first opened/created.
- Confirm if a duplicate incident was triggered manually from PagerDuty, or from the PagerDuty widget in the issue sidebar.
- Check if there are any project-level or global-level automations which would have created a duplicate ticket.
- Verify if there is a duplicate configuration rule mapping the Jira project and issue type to the same PagerDuty service.
TLS Certificate Errors
Most commonly, this error occurs when:
- A certificate in the chain has expired
- The certificate being used is self-signed or from an issuer not trusted by PagerDuty
- The certificate chain is out of order
- There is a duplicate certificate in the certificate chain
PagerDuty expects all certificates in the chain to be active, sent in the correct order (with no duplicates) and signed by a trusted root. The below openssl command, or a tool like SSL Labs, may be helpful in identifying issues with the certificate chain.
Please note that the port for your Jira instance may be different from the default 443:
openssl s_client -connect <jira url>:443 -showcerts
Please see our article on trusted root certificates for more information.
A PagerDuty Incident Generated Multiple Jira Tickets
This may occur if your Jira instance takes 15 seconds or more to complete the entire process: create issue, sync notes and status, update fields, etc. In this case, the integration will retry the webhook, resulting in the creation of a duplicate Jira issue.
Incident Notes & Issue Comments are not Syncing
This may occur if:
- The user selected to enable notes sync is no longer active in your PagerDuty account.
- Your Jira Admin has defined specific project permissions required to post issue comments.
- Your Jira instance was experiencing a network issue at the time the comment was being created.
Priority is not syncing between Jira and PagerDuty
To map priorities between Jira and PagerDuty, your PagerDuty account must have access to the priorities feature, and your PagerDuty Admin must Configure Incident Priority.
If your account does not meet these two requirements, then you will see the following message:
![](https://files.readme.io/1b6a268-jira-cloud-tg-priority-mapping-error.png)
Additionally, priorities must be available for the issue type defined in your configuration rule. If the issue type does not meet this requirement, then you will see a message that priorities are not available for the issue type. Please see the example below:
![](https://files.readme.io/74a87ce-jira-cloud-tg-priority-mapping-error-2.png)
Your Jira Admin should verify the following:
- The Jira issue priorities that you want are mapped to a priorities scheme in Jira.
- The priorities scheme is correctly associated to the Jira project.
- The priority field is available for that issue type in the Jira project (Project Settings > Issue Types > select an issue type to view the available fields).
Create a Test Issue Did not Create a Test Issue
- Please note that the Create a Test Issue feature creates an issue in Jira Cloud, but it does not trigger an incident in PagerDuty.
- When the test issue is created, the integration will transition the test issue from the Jira issue status mapped to triggered to the issue status mapped to resolved. Therefore, you will need a workflow transition in Jira that directly connects these two issue statuses.
- Some Jira issue fields may be required:
a. Confirm which fields are required for that Jira project and issue type.
b. Confirm the data type expected for each field.
There should be a PagerDuty attribute mapped to each required field. The PagerDuty attribute data type should also match the data type expected by that field.
![](https://files.readme.io/001e4f4-jira-cloud-tg-field-mapping.png)
JQL Tips
- To test the JQL statement in your configuration rule: paste the JQL statement in your configuration rule to Jira, to confirm if that query returns the Jira issue as expected.
- If your company has access to Atlassian Intelligence, you can leverage this tool to assist you in writing the JQL statement. Alternatively, you can explore other AI chat assistants if access to this tool is not available. To test the JQL statement, use the testing method above.
- For additional details regarding JQL, please reference the resources linked below.
Additional Resources
JQL Fields
What Information Does the PagerDuty Support Team Need to Help Troubleshoot Jira Cloud Issues?
- Which PagerDuty service <> Jira project connection was affected
- XML export of the relevant Jira issue
- Logs or records showing the updates that have been made to the Jira issue
- Screenshot of the workflow for that Jira project and issue type, from Open ---> Done/Closed
- Screenshots or records of the global/project automations associated to the Jira project
- Screenshot of the available issue types for the affected Jira project
- Screenshot of available issue fields for the affected issue type, including the data type defined for these fields.
Updated 8 days ago