Documentation Plugins Azure Data Explorer Troubleshooting

Troubleshoot Azure Data Explorer data source issues

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

First troubleshooting steps

If the data source doesn’t work and you’re not sure where to start, or the error message isn’t specific, work through this checklist before deeper troubleshooting:

1. Confirm you’re on the latest plugin version and it’s compatible with your Grafana version. Refer to Version and upgrade guidance.
2. Verify the Default cluster URL is correct and reachable from the Grafana server.
3. Confirm the selected authentication method is fully configured, and that the identity has viewer access to the database. Refer to Authentication errors.
4. Click Save & test and note the exact message. Use it to find the matching section in this guide.
5. Review the Grafana server logs and the browser developer console for plugin errors. Refer to Enable debug logging.
6. Confirm the problem isn’t on the Azure side, such as a paused cluster, changed permissions, or a networking change.

Version and upgrade guidance

Many Azure Data Explorer 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.

Supported Grafana versions

The current plugin release supports the following Grafana versions. If your Grafana version is earlier than the minimum patch for its minor release, the plugin might fail to load or behave unexpectedly.

Grafana versions earlier than 11.6.11 aren’t supported. Compatibility requirements can change between plugin releases. To confirm the requirement for a specific plugin version, check the Dependencies section on the plugin catalog page, or the grafanaDependency field in that version’s plugin.json.

Check and update the plugin version

1. Navigate to Connections > Plugins and data > Plugins.
2. Search for the plugin 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

• Configuration tab is blank or incomplete. Older versions might not render all settings fields.
• 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.

Plugin fails to load, crashes, or freezes after a version change

Symptoms:

• The plugin fails to load after a plugin or Grafana version update.
• A specific feature crashes, such as annotations or schema loading.
• Grafana becomes unresponsive when you select Azure Data Explorer as a data source.

Solutions:

1. Check for a version mismatch. Confirm your Grafana version meets the minimum patch in Supported Grafana versions.
2. Clear your browser cache and reload. Stale frontend assets left over from an upgrade can cause loading failures and freezes.
3. Review the Grafana server logs for plugin load errors, and the browser developer console for frontend errors.
4. If the problem started immediately after a plugin update, roll back to the last version that worked, then upgrade again once a fixed release is available. For install and rollback commands, refer to Upgrade the plugin.

Authentication regressions after a Grafana upgrade

Authentication that previously worked can break after a Grafana upgrade because the underlying Azure authentication behavior is provided by Grafana rather than the plugin. Managed Identity and On-Behalf-Of authentication are the most commonly affected methods, and regressions are typically resolved in a later patch release.

If authentication stops working immediately after an upgrade and your Azure configuration hasn’t changed:

1. Confirm the failure started with a specific Grafana version by checking the Grafana release notes.
2. Upgrade to the latest patch release for your Grafana minor version, which often contains the fix.
3. Verify the plugin version is compatible with your Grafana version. The plugin requires Grafana 11.6.11 or later.

Authentication errors

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

“Access denied” or authorization errors

Symptoms:

• Save & test fails with an authorization error.
• Queries return access denied messages.
• Databases or tables don’t load in drop-downs.

Possible causes and solutions:

Managed Identity authentication fails after a Grafana upgrade

Symptoms:

• Managed Identity authentication worked before a Grafana upgrade and now fails.
• The data source returns authentication errors even though the managed identity and its permissions are unchanged.

Solutions:

1. Confirm managed_identity_enabled is still set in the [azure] section of your Grafana configuration.
2. Verify the managed identity still has viewer access to the database.
3. If the failure began right after an upgrade, treat it as a version regression. Refer to Authentication regressions after a Grafana upgrade.

On-Behalf-Of authorization failures

Symptoms:

• Queries fail after a user signs in with OBO authentication.
• Alert rules stop returning data.

Solutions:

1. Verify the adxOnBehalfOf feature toggle is enabled.
2. Confirm the Azure Data Explorer user_impersonation API permission is granted and Admin consent is enabled.
3. Confirm the [auth.azuread] scopes setting contains openid email profile and that ID tokens are enabled.
4. Don’t use OBO authentication for alerting. Alert rules stop working after the rule’s creator signs out.

Connection errors

These errors occur when Grafana can’t reach the Azure Data Explorer cluster.

Connection refused or timeout errors

Symptoms:

• The data source test times out.
• Queries fail with network errors.

Solutions:

1. Verify network connectivity from the Grafana server to the cluster URL.
2. Check that firewall rules allow outbound HTTPS on port 443.
3. If you enforce trusted endpoints, verify the cluster URL matches an allowed endpoint. Refer to Enforce trusted endpoints.
4. For private networks in Grafana Cloud, configure Private data source connect.

Connected to the cluster but can’t list clusters

Symptoms:

• Save & test reports Success connecting to Azure Data Explore, but unable to connect to Azure Resource Graph to get clusters.
• Queries against your database work, but the cluster drop-down doesn’t populate automatically.

Solutions:

The data source connected to your cluster, but it couldn’t query Azure Resource Graph to enumerate clusters. Azure Resource Graph requires the identity to have Reader access at the subscription level. Grant the identity the Reader role, or enter the cluster URL manually in the query header. For role assignment steps, refer to Configure the Azure Data Explorer data source.

Private Data Source Connect issues

Private Data Source Connect (PDC) is a Grafana Cloud feature that connects to clusters on a private network. Because traffic passes through the PDC agent instead of a direct connection, it introduces extra components that can affect reliability.

Symptoms:

• The connection works with a direct connection but fails or is unstable through PDC.
• Queries succeed intermittently through PDC.

Solutions:

1. Confirm the PDC agent is running and connected. Queries fail whenever the agent is down.
2. Verify the PDC network path can reach the cluster URL on outbound HTTPS port 443.
3. Confirm the data source is assigned to the correct PDC connection in its settings.
4. To isolate whether an issue is specific to PDC, temporarily test with a direct connection if your network allows it.

For setup details, refer to Private data source connect.

Intermittent connection failures

Symptoms:

• The data source works most of the time but fails intermittently.
• Failures don’t correlate with a configuration change in Grafana.

Solutions:

1. Check the health of the Azure Data Explorer cluster. A paused, throttled, or scaling cluster can cause intermittent failures.
2. Confirm the cluster and its permissions haven’t changed on the Azure side.
3. If failures coincide with a Grafana stack redeployment or restart, retest after the deployment stabilizes. Transient errors during a redeployment usually resolve on their own.
4. Review the Grafana server logs to correlate failures with cluster-side or network events.

Query errors

These errors occur when executing queries against the cluster.

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:

Query timeout

Symptoms:

• A query runs for a long time and then fails.
• The error mentions a timeout or query limits.

Solutions:

1. Narrow the time range to reduce the data volume.
2. Add filters to reduce the result set.
3. Increase the Query timeout value in the data source Additional settings.
4. Avoid resource-intensive mv-expand operations on large dynamic columns.

Background features fail under Current User authentication

Symptoms:

• Dashboards work interactively, but alerting, recorded queries, or reporting fail.
• Background requests return authentication errors with no signed-in user.

Solutions:

1. Enable fallback service credentials.
2. Enable the idForwarding feature toggle so Grafana can distinguish background requests from user requests.
3. Confirm the fallback identity has viewer access to the database.

Template variable errors

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

Variables return no values

Solutions:

1. Test the data source connection in the data source settings.
2. Verify you selected the correct Query Type and completed the required fields, such as Cluster, Database, or Table.
3. For a Kusto Query variable, verify the query uses project to return a single column of string values.
4. Verify the identity has permission to list the requested resources.

Provisioning errors

These errors occur when you provision the data source with Terraform, YAML files, or the HTTP API instead of the UI.

Provisioning fails with an invalid UID

Symptoms:

• Terraform or API provisioning fails when you set an explicit uid on the data source.
• The error mentions an invalid or too-long UID.

Solutions:

1. Keep the uid to 40 characters or fewer. Grafana rejects a data source UID that exceeds 40 characters.
2. Use only letters, numbers, dashes (-), and underscores (_) in the UID.
3. If you don’t need a fixed UID, omit the field and let Grafana generate one.

Data source is overwritten or reverts after provisioning

Symptoms:

• Configuration changes made in the UI disappear after a restart.
• Two provisioning methods appear to compete.

Solutions:

Manage each data source with a single provisioning method. If you provision the same data source with both YAML files and Terraform, the two methods can overwrite each other. Refer to Provision the data source.

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 Azure Data Explorer 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 here and still encounter issues:

1. Check the Grafana community forums for similar issues.
2. Review the azure-data-explorer-datasource GitHub issues for known bugs.
3. Consult the Azure Data Explorer documentation for service-specific guidance.
4. Contact Grafana Support if you’re an Enterprise, Cloud Pro, or Cloud Advanced customer.
5. When reporting issues, include the Grafana version, plugin version, error messages (with sensitive information redacted), steps to reproduce, and relevant configuration (with credentials redacted).