Documentation Plugins Azure DevOps Troubleshooting

Troubleshoot Azure DevOps data source issues

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

Authentication errors

These errors occur when the personal access token (PAT) is invalid, expired, or doesn’t have the required permissions.

“invalid URL” or “invalid PAT”

Symptoms:

• Save & test fails immediately with invalid URL or invalid PAT.

Solutions:

1. Verify the URL field isn’t empty. It must contain your Azure DevOps organization URL (for example, https://dev.azure.com/<ORGANIZATION>).
2. Verify the PAT field isn’t empty. Click Reset if the field shows “Configured” and re-enter the token.

“Access denied” or “401 Unauthorized”

Symptoms:

• Save & test fails with an authorization or authentication error.
• Queries return access denied messages.
• Project or repository drop-downs are empty.

Possible causes and solutions:

“Health check failed with status code: N”

Symptoms:

• Save & test fails with a message like Health check failed with status code: 401 or Health check failed with status code: 404.
• This error occurs when the Secure Socks Proxy toggle is enabled.

Possible causes and solutions:

PAT authentication fails on Azure DevOps Server (on-prem)

Symptoms:

• Save & test fails on an on-premises Azure DevOps Server instance.
• Authentication redirects or federation errors occur.

Solutions:

1. Set the Username field in Optional Configuration to the PAT owner’s username.
2. Verify the server URL is correct and accessible from the Grafana server.
3. If connecting from Grafana Cloud to an on-premises instance, configure Private data source connect and enable the Secure Socks Proxy toggle.

“Failed to get settings”

Symptoms:

• Save & test fails with Failed to get settings.

Solutions:

1. Verify the data source configuration is saved. Click Save & test rather than just Test.
2. If provisioning the data source, check that the YAML file has the correct structure with jsonData.url and secureJsonData.patToken. Refer to Provision the data source.

Health check succeeds but shows 0 projects

Symptoms:

• Save & test succeeds with healthcheck successful. 0 projects found.
• Project drop-down is empty.

Solutions:

1. Verify the PAT has access to at least one project in the organization.
2. Check that the URL points to the correct organization.
3. In Azure DevOps, verify your user account has been added to the organization and has permission to view projects.

Connection errors

These errors occur when Grafana can’t reach the Azure DevOps endpoints.

“Connection refused” or timeout errors

Symptoms:

• Save & test times out.
• Queries fail with network errors.
• Intermittent connection failures.

Solutions:

1. Verify network connectivity from the Grafana server to the Azure DevOps endpoint.
2. Check firewall rules allow outbound HTTPS (port 443) to dev.azure.com or your on-premises server.
3. For on-premises Azure DevOps Server behind a private network, configure Private data source connect if using Grafana Cloud.
4. Verify the URL doesn’t include a trailing slash or extra path segments.

Query errors

These errors occur when executing queries against the data source.

“No data” or empty results

Symptoms:

• Query executes without error but returns no data.
• Charts show “No data” message.

Possible causes and solutions:

“invalid query type” error

Symptoms:

• Query fails with an invalid query type error message.

Solutions:

1. Select a valid query type from the Query Type drop-down.
2. If the error persists after selecting a query type, delete the query panel and create a new one.

“should be a GUID” error

Symptoms:

• Query fails with an error containing should be a GUID.

Solutions:

Fields like Creator Id, Reviewer ID, and Repository ID expect UUID-formatted values (for example, a1b2c3d4-e5f6-7890-abcd-ef1234567890). Verify you’re entering a valid GUID, not a display name or other identifier. You can find user GUIDs in Azure DevOps under organization settings or through the Azure DevOps REST API.

“invalid project id” or “invalid pipeline id”

Symptoms:

• Query fails with invalid project id or invalid pipeline id.

Solutions:

1. Verify you’ve selected a project from the Project drop-down. Most query types require a project selection.
2. For Pipeline Runs queries, verify you’ve selected a pipeline from the Pipeline drop-down. Both a project and a pipeline are required for this query type.
3. If using a template variable for the project or pipeline, verify the variable is resolving to a valid value. Check the variable selector at the top of the dashboard.

Query timeout

Symptoms:

• Query runs for a long time and then fails.
• Error mentions timeout or query limits.

Solutions:

1. Narrow the dashboard time range to reduce the volume of data returned.
2. Add filters (such as Status, Branch, or Definition Id) to reduce the result set.
3. Use the Top field (available for Releases and Release Deployments) to limit the number of results.

Annotation errors

These errors occur when using annotations with the data source.

Annotations don’t appear on panels

Possible causes and solutions:

Template variable errors

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

Variables return no values

Possible causes and solutions:

Cascading variables show errors or wrong results

Symptoms:

• A Repositories variable filtered by a Projects variable shows errors or returns repositories from the wrong project.
• The variable drop-down briefly shows an error before populating.

Solutions:

1. In Dashboard settings > Variables, ensure the Projects variable appears before the Repositories variable in the list. Drag to reorder if needed.
2. Verify the Repositories variable uses the correct variable reference (for example, $project) in the Project filter.
3. Set the Repositories variable refresh to On dashboard load so it re-evaluates after the parent variable resolves.

Variables are slow to load

Solutions:

1. Set variable refresh to On dashboard load instead of On time range change if the variable values don’t depend on the time range.
2. Set the Projects limit in the data source configuration to a reasonable value for your organization. A high limit causes the /projects resource call to return more data, slowing variable loading.

Enable debug logging

To capture detailed error information for troubleshooting:

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

   ini Copy

   [log]
   level = debug

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

3. Look for entries containing grafana-azuredevops-datasource for plugin-specific log messages.

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. Consult the Azure DevOps REST API documentation for service-specific guidance.
3. Contact Grafana Support if you’re an Enterprise, Cloud Pro, or Cloud Advanced user.
4. When reporting issues, include:
   • Grafana version and plugin version
   • Error messages (redact sensitive information)
   • Steps to reproduce
   • Relevant data source configuration (redact the PAT)