Documentationbreadcrumb arrow Pluginsbreadcrumb arrow Jenkins data sourcebreadcrumb arrow Troubleshooting
Grafana Cloud Enterprise
Last reviewed: August 6, 2026

Troubleshoot Jenkins data source issues

This document provides solutions to common issues you may encounter when configuring or using the Jenkins data source. For configuration instructions, refer to the Jenkins data source overview.

Both authentication and network problems surface the same Unable to connect to Jenkins message during Save & test; read the detail after Error: to tell them apart, then jump to Authentication errors or Connection errors.

License and setup errors

These errors occur when the Enterprise plugin isn’t licensed, activated, or installed by an administrator.

“Plugin health check failed”

Symptoms:

  • Save & test returns a generic Plugin health check failed error.
  • The Install button doesn’t appear in the plugin catalog.

Possible causes and solutions:

CauseSolution
Plugin not activatedConfirm your Grafana Cloud plan is Pro or Advanced, or that your Grafana Enterprise license includes grafana-jenkins-datasource.
Missing permissionsSign in with an account that has the Organization administrator role.
Plugin not installedInstall the plugin. Refer to Install and upgrade the Jenkins data source plugin.

Version and upgrade guidance

Many Jenkins data source issues are caused by running an outdated plugin version. Before deeper troubleshooting, confirm you’re on the latest version, because upgrading resolves a wide range of problems.

Note

On Grafana Cloud, the Jenkins plugin is managed by Grafana and updates automatically. On self-managed Grafana, you must update Enterprise plugins manually. In other managed environments, such as Azure Managed Grafana, the plugin version is controlled by the platform provider and can lag behind the latest release.

Check and update the plugin version

To check and update the plugin version:

  1. Navigate to Connections > Plugins and data > Plugins.
  2. Search for Jenkins and open its page.
  3. Review the installed version and the latest available version.
  4. If an update is available and you’re on self-managed Grafana, click Update.

Symptoms of an outdated plugin version

The following symptoms often indicate an outdated plugin version:

  • Configuration tab is blank or incomplete. Older versions may not render all settings fields, which can look like settings were lost.
  • Connection failures with unhelpful errors. Severely outdated versions can fail to connect at all.
  • Intermittent Plugin unavailable or HTTP 500 errors, especially in managed environments with many panels.

Authentication errors

These errors occur when credentials are invalid, missing, or don’t have the required permissions.

“Unable to connect to Jenkins” with an authentication error

Symptoms:

  • Save & test fails with Unable to connect to Jenkins followed by an authentication or authorization message.
  • Queries return access-denied messages.
  • The project drop-down in the query editor doesn’t load.

Possible causes and solutions:

CauseSolution
Invalid credentialsVerify the User and Password in the data source configuration. Regenerate the credentials in Jenkins if necessary.
API token expired or revokedCreate a new API token in Jenkins under Your Profile > Configure > API Token and update the Password field.
Insufficient permissionsConfirm the user has the Overall/Read permission and read access to the projects and nodes you query.
Anonymous access disabledIf your Jenkins instance requires authentication, provide a User and Password. Anonymous requests are rejected.

Connection errors

These errors occur when Grafana can’t reach your Jenkins instance.

“Unable to connect to Jenkins” with a network error

Symptoms:

  • The data source test times out or fails with a network error.
  • Queries fail intermittently with connection errors.

Solutions:

  1. Verify the URL is correct and reachable from the Grafana server, including the scheme (https://) and port.
  2. Verify network connectivity and firewall rules allow outbound access from Grafana to the Jenkins instance.
  3. Confirm the Remote Access API is enabled on your Jenkins instance.
  4. For a Jenkins instance on a private network, enable Private Data Source Connect (PDC) and turn on the Enable Secure Socks Proxy toggle in the data source configuration.

When the connection succeeds, Save & test displays Data source is working.

Query errors

These errors occur when running queries against the data source.

“No data” or empty results

Symptoms:

  • A query runs without error but returns no data.
  • Panels show a No data message.

Possible causes and solutions:

CauseSolution
Time range doesn’t contain dataFor a Project Builds query, expand the dashboard time range to include builds that ran in that window.
No project selectedThe Project Builds query requires a project. Select a project in the query editor.
Permissions issueConfirm the user has read access to the specific project, node, or queue you’re querying.
No matching resourcesVerify the projects, nodes, or labels exist in Jenkins.

Project drop-down is empty

Symptoms:

  • The project selector in a Project Builds query shows no options.

Solutions:

  1. Verify the data source connection with Save & test.
  2. Confirm the user has permission to list projects in Jenkins.
  3. Check that projects exist on the Jenkins instance.

Template variable errors

These errors occur when using template variables with the data source.

Variables return no values

Issues where a Projects query variable returns no options.

Solutions:

  1. Verify the data source connection is working by testing it in the data source settings.
  2. Confirm the Projects query type is selected for the variable.
  3. Verify the user has permission to list projects in Jenkins.

Enable debug logging

To capture detailed error information for troubleshooting:

  1. Set the Grafana log level to debug in the configuration file:

    ini 
    [log]
level = debug

  2. Review logs in /var/log/grafana/grafana.log (or your configured log location).

  3. Look for grafana-jenkins-datasource entries that include request and response details.

  4. Reset the log level to info after troubleshooting to avoid excessive log volume.

Get additional help

If you’ve tried the solutions in this document and still encounter issues:

  1. Check the Grafana community forums for similar issues.
  2. Review the Jenkins Remote Access API documentation for service-specific guidance.
  3. Contact Grafana Support if you’re an Enterprise, Cloud Pro, or Cloud Contracted user.
  4. When reporting issues, include:
    • Grafana version and plugin version
    • Error messages (redact sensitive information)
    • Steps to reproduce
    • Relevant configuration (redact credentials)