public/grafana
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

made updates based on feedback

Browse Source
This commit is contained in:
Larissa Wandzura
2026-01-09 09:48:21 -06:00
parent e81769147f
commit e83c88bf75
1 changed files with 13 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/sources/datasources/prometheus/troubleshooting/index.md
+13 -8
View File
@@ -14,11 +14,11 @@ labels:
- enterprise
- oss
menuTitle: Troubleshooting
title: Troubleshoot issues with the Prometheus data source
title: Troubleshoot Prometheus data source issues
weight: 600
---
# Troubleshoot issues with the Prometheus data source
# Troubleshoot Prometheus data source issues
This document provides troubleshooting information for common errors you may encounter when using the Prometheus data source in Grafana.
@@ -53,6 +53,7 @@ The following errors occur when Grafana cannot establish or maintain a connectio
1. Check the network latency between Grafana and Prometheus.
1. Verify that Prometheus is not overloaded or experiencing performance issues.
1. Increase the **Query timeout** setting in the data source configuration under **Interval behavior**.
1. Check the [Grafana server timeout configuration](https://grafana.com/docs/grafana/latest/setup-grafana/configure-grafana#timeout) for server-level timeout settings.
1. Reduce the time range or complexity of your query.
1. Check if any network devices (load balancers, proxies) are timing out the connection.
@@ -83,7 +84,7 @@ The following errors occur when there are issues with authentication credentials
1. Verify that the username and password are correct if using basic authentication.
1. Check that the authentication method selected matches your Prometheus configuration.
1. If using a reverse proxy with authentication, verify the credentials are correct.
1. For AWS SigV4 authentication, verify the IAM credentials and permissions.
1. For AWS SigV4 authentication, verify the IAM credentials and permissions. Alternatively, consider using the [Amazon Managed Service for Prometheus data source](https://grafana.com/grafana/plugins/grafana-amazonprometheus-datasource/) for simplified AWS authentication.
### Forbidden (403)
@@ -96,7 +97,7 @@ The following errors occur when there are issues with authentication credentials
1. Verify the user has read access to the Prometheus API.
1. Check Prometheus security settings and access control configuration.
1. If using a reverse proxy, verify the proxy is not blocking the request.
1. For AWS Managed Prometheus, verify the IAM policy grants the required permissions.
1. For AWS Managed Prometheus, verify the IAM policy grants the required permissions. Alternatively, consider using the [Amazon Managed Service for Prometheus data source](https://grafana.com/grafana/plugins/grafana-amazonprometheus-datasource/) for simplified AWS authentication.
## Query errors
@@ -108,6 +109,8 @@ The following errors occur when there are issues with PromQL syntax or query exe
**Cause:** The PromQL query contains invalid syntax.
**Alternative cause:** A proxy between Grafana and Prometheus requires authentication. When proxy authentication fails, the proxy redirects the request to an HTML authentication page. Grafana cannot parse the HTML response, which results in a parse error. This appears to be a query issue but is actually a proxy authentication issue.
**Solution:**
1. Check your query syntax for typos or invalid characters.
@@ -115,18 +118,20 @@ The following errors occur when there are issues with PromQL syntax or query exe
1. Ensure string values in label matchers are enclosed in quotes.
1. Use the Prometheus expression browser to test your query directly.
1. Refer to the [Prometheus querying documentation](https://prometheus.io/docs/prometheus/latest/querying/basics/) for syntax guidance.
1. If you have a proxy between Grafana and Prometheus, verify that proxy authentication is correctly configured. Check your proxy logs for authentication failures or redirects.
### Unknown metric name
### Query returns no data for a metric
**Error message:** "unknown metric name" or query returns no data
**Symptom:** The query returns no data and the visualization is empty.
**Cause:** The specified metric does not exist in Prometheus.
**Cause:** The specified metric does not exist in Prometheus, or there is no data for the selected time range.
**Solution:**
1. Verify the metric name is spelled correctly.
1. Check that the metric is being scraped by Prometheus.
1. Use the Prometheus UI to browse available metrics at `/graph` or `/api/v1/label/__name__/values`.
1. Use the Prometheus API to browse available metrics at `/api/v1/label/__name__/values`.
1. Use the [target metadata API](https://prometheus.io/docs/prometheus/latest/querying/api#querying-target-metadata) to verify which metrics a target exposes.
1. Verify the time range includes data for the metric.
### Query timeout limit exceeded