Jira data source

Troubleshooting

Troubleshoot Jira data source issues

This guide provides troubleshooting guidance for common issues with the Jira data source plugin.

Connection errors

These issues relate to establishing a connection between Grafana and your Jira instance.

Unable to connect to Jira

Error message: “Connection refused. The Jira server is not responding”

Cause: Grafana cannot establish a connection to the Jira server.

Solution:

Verify the Jira URL is correct and accessible from the Grafana server.
Check that port 8080 is enabled and not blocked by a firewall.
Ensure the Jira instance is running and responsive.
If using Jira Data Center or Jira Server, verify the server is accessible on your network.
Test connectivity by accessing the Jira URL directly in a browser from the Grafana server.

Invalid URL

Error message: “The URL cannot be verified. Double check the formatting and/or the URL.”

Cause: The Jira URL is malformed or incorrectly formatted.

Solution:

Verify the URL includes the protocol (https:// or http://).
Check for trailing slashes or extra characters in the URL.
Ensure the URL points to the root of your Atlassian instance, not a specific page or endpoint.
For Jira Cloud, the URL format should be https://your-domain.atlassian.net.
For Jira Data Center or Server, use the base URL of your Jira installation.

API endpoint not found

Error message: “The Jira API endpoint was not found. This usually indicates an incorrect Jira URL.”

Cause: The configured URL doesn’t point to a valid Jira API endpoint.

Solution:

Verify you’re using the correct Provider setting (Jira Cloud vs. Jira Data Center/Jira Server).
Check that the URL is the root URL of your Jira instance, not a project or issue URL.
For Jira Cloud, ensure the URL format is https://your-domain.atlassian.net.
For Jira Data Center or Server, verify the context path is correct if your instance uses one.

Proxy connection error

Error message: “Proxy connection error”

Cause: Issues with proxy configuration between Grafana and Jira.

Solution:

Check your proxy settings in Grafana’s configuration.
Verify the proxy server is running and accessible.
Ensure the proxy allows connections to your Jira instance.
If using Private Data Source Connect (PDC), verify the PDC agent is running and properly configured.

Private data source connect (PDC) issues

Cause: PDC connection is not properly configured or the agent is not running.

Solution:

Verify the PDC agent is installed and running in your network.
Check that the PDC connection is properly configured in the data source settings.
Ensure the PDC agent has network access to your Jira instance.
Review PDC agent logs for connection errors.
Refer to Configure Grafana private data source connect (PDC) for setup instructions.

Authentication errors

These errors occur when credentials are invalid or permissions are insufficient.

Authentication failed

Error message: “Authentication failed. This could be due to: 1) Invalid username/email or API token, or 2) Valid credentials with insufficient permissions. Please verify your credentials and permissions”

Cause: The provided credentials are invalid or the user lacks necessary permissions.

Solution:

Verify the email address matches the Atlassian account associated with the API token.
Generate a new API token and update the data source configuration:
- Go to Manage API tokens for your Atlassian account.
- Create a new token and copy it immediately (tokens are only shown once).
Ensure the user account has access to the Jira projects you want to query.
Check that the API token hasn’t expired or been revoked.
If leaving the User email field empty, verify that Bearer token authentication is supported by your Jira instance.

Basic vs. Bearer authentication

Cause: Confusion about which authentication method is being used.

Solution:

If the User email field is populated, Basic authentication is used.
If the User email field is empty, Bearer token authentication is used.
For Jira Cloud, Basic authentication (email + API token) is the recommended method.
For Jira Data Center or Server, check which authentication methods your instance supports.

Insufficient permissions

Cause: The authenticated user doesn’t have permissions to access certain projects or issues.

Solution:

Verify the user has at least Browse Projects permission for the projects you want to query.
Check project-level permissions in Jira’s project settings.
For Jira Service Management queries, ensure the user has appropriate service desk permissions.
Contact your Jira administrator to review and adjust permissions if needed.

Query errors

These issues relate to JQL queries and data retrieval.

JQL syntax errors

Cause: The JQL query contains syntax errors.

Solution:

Validate your JQL syntax in Jira’s advanced search before using it in Grafana.
Ensure field names are spelled correctly and match Jira’s field names.
Use single quotes for string values: project = 'My Project'.
Check for unbalanced parentheses or quotes.
Refer to Use advanced search with Jira Query Language (JQL) for syntax guidance.

Example of correct JQL syntax:

project = 'TEST' AND assignee = 'Joe Smith' AND status != 'Done'

No data returned

Cause: The query returns no matching issues.

Solution:

Verify the JQL query returns results when run directly in Jira’s advanced search.
Check that the selected fields exist on the issues being queried.
Increase the Limit value if you expect more results.
Verify the time range macros ($__timeFrom and $__timeTo) align with your issue dates.
Ensure the authenticated user has permission to view the issues.

Time range macros don’t filter correctly

Cause: Time range macros are used incorrectly in JQL.

Solution:

Use the correct macro syntax: $__timeFrom and $__timeTo.
Apply macros to date fields like createdDate, updatedDate, or resolutionDate.
Example: createdDate >= $__timeFrom AND createdDate <= $__timeTo.
Verify the dashboard time range includes the dates of your issues.

Custom fields not appearing

Cause: Custom field types from Jira add-ons may not be supported.

Solution:

Check if the custom field type is supported by the plugin.
Try selecting the field by its custom field ID (for example, customfield_10001).
Use the Extract fields transformation for fields returned as stringified JSON.
Note that some custom field types from third-party Jira add-ons are not supported (this is a known limitation).

Template variable issues

Cause: Template variables don’t work as expected in queries.

Solution:

Ensure the variable is correctly defined in the dashboard settings.
Use the correct variable syntax: $variableName or ${variableName}.
For multi-value variables, use the IN clause: assignee IN ($assignee).
Verify the variable query returns the expected values.
Check that the Jira data source is selected as the variable’s data source.

Performance issues

These issues relate to slow queries or timeouts.

Slow query execution

Cause: Queries return large amounts of data or Jira is slow to respond.

Solution:

Reduce the Limit value to return fewer issues.
Add more specific JQL filters to narrow down results.
Use indexed fields in JQL filters for better performance.
Use the dashboard time range to filter issues with $__timeFrom and $__timeTo macros.
Consider splitting complex queries into multiple smaller queries.

Query timeout

Cause: The query takes too long to complete.

Solution:

Reduce the number of fields selected in the query.
Lower the Limit value.
Simplify your JQL filter.
Check if Jira itself is experiencing performance issues.
Consider using Grafana’s caching features to reduce load on Jira.

Transformation issues

These issues relate to using Grafana transformations with Jira data.

Linked issues not displaying correctly

Cause: Linked issues are returned as stringified JSON and need transformation.

Solution:

Apply the Extract fields transformation with:
- Source: Linked issues
- Format: JSON
- Path: inwardIssue.key or outwardIssue.key
Create separate queries for inward and outward linked issues.
Use the Merge transformation to combine results.
Refer to the Jira JSON fields demo dashboard for a complete example.

Group by transformation not working

Cause: Fields are not compatible with grouping or aggregation.

Solution:

Ensure the field you’re grouping by contains consistent values.
Verify numeric fields are selected for aggregation functions like Total or Mean.
Check that the field names match exactly (field names are case-sensitive).
Use Organize fields transformation to rename fields if needed.

Other common issues

The following issues don’t produce specific error messages but are commonly encountered.

Missing data source configuration

Error message: “Your data source configuration is incomplete and missing certain fields. Please view inline errors above.”

Cause: Required configuration fields are not populated.

Solution:

Ensure the URL field is populated with your Jira instance URL.
Provide the API token in the authentication section.
Select the correct Provider (Jira Cloud or Jira Data Center/Jira Server).
Click Save & test to validate the configuration.

Dashboard import issues

Cause: Pre-made dashboards don’t work after import.

Solution:

Verify the Jira data source is correctly configured and tested.
Check that the data source name matches the one expected by the dashboard.
Update dashboard variables to match your Jira projects and fields.
Some fields may need adjustment based on your Jira configuration.

Results appear distorted or incomplete

Cause: The query limit is lower than the actual number of issues.

Solution:

Increase the Limit value to include all relevant issues.
If calculating metrics (like velocity or average time), ensure the limit includes all issues in the scope.
For example, if a Sprint has 100 issues but the limit is 50, metrics will only reflect 50 issues.