Jira Server Troubleshooting Guide
Pre Checks
1. IP Safelisting Requirements
Before starting the troubleshooting process, please ensure that the required PagerDuty IP addresses have been safelisted.
2. Jira Server Compatibility Requirements
Your Jira Data Center/Jira Server version should be compatible with the integration version you have installed. For more information, please reference the compatibility table linked below.
3. Connection Credentials
In Jira, navigate to the PagerDuty application under Administration PagerDuty settings Account Integration tab. The credentials must be valid for the PagerDuty and Jira connection.
- For URLs, be sure to specify http or https in the field. If the protocol is not specified, the integration will use HTTP.
- The user credentials should have read/write access to the connected projects and they should be basic authorization credentials (i.e., username and password), not SSO.
- The REST API Key should be a full access key (i.e., not a read-only API key).
General Troubleshooting
In Jira, under the User mapping tab:
- There should be a fallback user mapping in the User mapping configuration section, in case the Jira action/PagerDuty action cannot be attributed to a linked user account.
If the issue persists after completing the pre-checks and general troubleshooting steps, please refer to the following section for more specific troubleshooting steps.
Troubleshoot Common Jira Server Issues
PagerDuty Incident did not Create a Jira Issue
1. Project Permissions
In your Jira project settings, navigate to Permissions. In the permission scheme verify which users, groups, and roles can create issues within the project.
- Has your Jira admin assigned the create issues permission to the Jira integration user or their group? Alternatively, do they have a project role that has permissions to create issues?
2. Issue Types
In your Jira project settings, navigate to Issue types. In the issue types scheme, confirm which issue types are available for your project.
3. Required Fields
In your project settings, navigate to Fields.
- In the fields scheme, check which fields are available for the affected issue type.
- In the fields scheme, check which fields are required/mandatory for the affected issue type.
4. Check Webhooks
On Jira's mapping Rules page, confirm that there is a mapping connecting the Jira project to a PagerDuty service. Next, check that the connection is enabled.
Click Check webhooks to the right of the mapping Rules page. Select the options above, Fix missing or useless webhooks and Both Jira and PagerDuty webhooks, to fix broken/invalid webhooks, then run the check.
5. Mapping Rules
Locate the rule connecting the PagerDuty service to your Jira project. Scroll down to the Create Jira issues from PagerDuty incidents section.
- Confirm the rule is configured to create a Jira issue when a PagerDuty incident is triggered.
- The PagerDuty incident should match the priority and urgency conditions.
If this option is not enabled, responders will have to manually trigger incidents from the incident page by selecting Create Jira Issue from the More dropdown.
If the project has required/mandatory fields for that issue type:
- Your Jira administrator can populate custom fields with a default value:
- You can add an action to map Jira fields to a PagerDuty incident attribute.
6. Additional Checks
- The PagerDuty attribute should match the data type expected for the Jira field.
- Your Jira administrator can check if there are any conflicting automations configured to process incoming webhooks, or handle automatic issue creation.
Jira Issue did not Trigger a PagerDuty Incident
1. Check Webhooks
On Jira's mapping Rules page, confirm if there is a mapping between the Jira project and the PagerDuty service. Next, check that the connection is enabled.
Click Check webhooks to the right of the mapping Rules page. Select the options above, Fix missing or useless webhooks and Both Jira and PagerDuty webhooks, to fix broken/invalid webhooks, then run the check.
2. Mapping Rules
Locate the rule connecting the PagerDuty service to your Jira project. Scroll down to the section Automatically create PagerDuty incidents from Jira issues.
- Confirm that the Jira issue matches the project and issue type defined in your rule.
- Copy the JQL statement, and search for Jira issues matching the condition. Does the Jira issue appear in the search results as expected?
- Verify that On issue create is selected.
If Automatically create PagerDuty incidents from Jira issues is not enabled, responders will have to manually trigger a PagerDuty incident from the PagerDuty app in the issue sidebar.
PagerDuty Incident Status and Jira Issue Status did not Sync
1. Mapping Rules
Locate the rule connecting the PagerDuty service to your Jira project. Scroll down to the section Automatically update Jira Issue.
- Confirm there is an action mapping the PagerDuty incident status to the Jira issue status.
Scroll down to the section Automatically update PagerDuty incident.
- Confirm there is an action mapping the Jira issue status to the PagerDuty incident status.
The PagerDuty application cannot transition issues/incidents to or from statuses that are not mapped in your rule.
2. Issue Workflow
In your Jira project settings, navigate to Workflows.
- There should be a workflow scheme associated to the issue type.
- Check if there is a workflow transition for that project and issue type, which would allow the issue to transition directly from the current status to the desired status.
3. Additional Checks
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 Jira:
- Your Jira administrator can check if there are any conflicting automations transitioning the Jira issue to a different status than the one you expected.
- Your Jira administrator can check if there are any conflicting automations transitioning the Jira issue to an unmapped status.
TLS Certificate Errors
1. Troubleshooting TLS Certificate Errors
Most commonly, TLS certificate errors 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
used in the example below:
openssl s_client -connect <jira url>:443 -showcerts
For more information regarding PagerDuty trusted root certificates, please reference the article below:
Priority is not syncing between Jira and PagerDuty
1. Priorities Feature
To map priorities between Jira and PagerDuty, your PagerDuty account must have access to the Incident Priority feature, and your PagerDuty administrator must Configure Incident Priority.
In PagerDuty, review the Priority Level column on the left, to confirm that the levels are labeled as expected.
2. Priority Scheme
In your Jira project's settings, navigate to Priorities.
- Verify that the correct priority scheme is associated to your project.
- Verify that the priority you were expecting is available in the priority scheme.
3. Priority Mapping
Set Priority for a PagerDuty Incident
Locate the rule connecting the PagerDuty service to your Jira project. Scroll down to the section Automatically create PagerDuty incidents from Jira issues.
- This section should contain mappings between the priorities defined in your JQL statements and the associated PagerDuty Incident Priorities.
Set Priority for a Jira Issue
Scroll down to the section Create Jira issues from PagerDuty incidents.
- This section should contain mappings between your PagerDuty incident priorities and the associated Jira issue priorities.
4. Additional Checks
In PagerDuty:
- On an incident's details page under the heading Synced With, 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.
- On an incident's details page, check if there is an Incident Priority assigned to the incident.
In Jira:
- Your Jira administrator can check if there are any conflicting automations configured to set the issue priority.
PagerDuty Incident Fields and Jira Issue Fields did not Sync
1. Screens and Screen Schemes
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.
- In Jira, navigate to Project settings Screens. This should allow you to view the screen scheme associated to your Jira project.
- Click on the screen scheme to view the issue types associated to the scheme, and the screens associated to each Jira issue operation.
- Select the Create Issue screen to view the available fields for the create issue operation.
In your project settings, navigate to Fields. In the fields scheme, check which fields are available for the affected issue type.
2. Field Mapping
Locate the rule connecting the PagerDuty service to your Jira project. Scroll down to the section Automatically create PagerDuty incidents from Jira issues.
- This section should contain an action that maps the PagerDuty incident field to a Jira issue field.
Scroll down to the section Create Jira issues from PagerDuty incidents.
- This section should contain an action that maps the Jira issue field to a PagerDuty incident field.
3. Additional Checks
- PagerDuty attributes should match the data type expected for each Jira field.
- Your Jira administrator can check if there are any conflicting automations configured to populate the affected issue field.
- The Jira Integration user should be granted permission to Edit issues within the project.
A Jira Ticket Triggered Multiple PagerDuty Incidents
Mapping Rules
In Jira, navigate to your mapping Rules a check the JQL trigger condition within each rule.
Check if there are multiple rules with a JQL trigger condition matching the Jira ticket.
Review the changes/updates to the Jira issue, to confirm if any updates caused the Jira issue to match the trigger condition again.
Incident Notes and Issue Comments are not Syncing
Comment Permissions
In Jira, navigate to your project settings' Permissions. Check the permission scheme to confirm which users, groups, and roles can comment on issues within the project.
Mapping Rules
In Jira, locate the rule connecting the PagerDuty service to your Jira project. Confirm that the Sync comments & notes setting is enabled.
Additional Checks
On a PagerDuty incident's details page under the heading Synced With, 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.
JQL Tips and Tricks
- 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.
- There are some AI chat assistants that may be able to help you construct/review your JQL statement. 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
Updated 8 days ago