InfluxDB data source on Grafana Labs

Configure the InfluxDB data source

Tue, 27 Oct 2026 11:15:42 +0000

Configure the InfluxDB data source

This document explains how to configure the InfluxDB data source and describes the available configuration options.

Key concepts

If you’re new to InfluxDB, these terms are used throughout the configuration:

Term	Description
Bucket	A named location in InfluxDB 2.x and 3.x where time-series data is stored, equivalent to a database in 1.x.
Organization	An InfluxDB 2.x workspace that groups users, buckets, and dashboards.
DBRP mapping	Database and Retention Policy mapping that lets InfluxQL queries work against InfluxDB 2.x buckets.
Measurement	A logical grouping of fields, tags, and timestamps in InfluxDB, similar to a table in a relational database.
Retention policy	An InfluxDB 1.x setting that defines how long data is kept before automatic deletion.
Token	An authentication credential used to access the InfluxDB API in 2.x and 3.x.

Before you begin

To configure the InfluxDB data source, you must have the Administrator role.

Grafana and Grafana Cloud don’t provide a hosted InfluxDB service. The data source connects to an InfluxDB instance that you run and manage yourself, or to one of InfluxData’s cloud products. You must have a running InfluxDB instance before you configure the data source.

InfluxData provides three query languages:

SQL - Standard SQL query language for InfluxDB 3.x and newer cloud products (Cloud Serverless, Cloud Dedicated, Clustered). InfluxData recommends SQL for new deployments. It supports JOINs, subqueries, and standard SQL functions. Refer to InfluxDB SQL reference for the full list of supported statements, operators, and functions.
InfluxQL - An SQL-like query language developed by InfluxData, available across all InfluxDB versions. InfluxQL doesn’t support advanced functions such as JOINs. Refer to the InfluxQL reference for details.
Flux - A functional data scripting language for InfluxDB 2.x. Flux is not supported on InfluxDB 3.x. Refer to Query InfluxDB with Flux for a basic guide.

Note
If you’re migrating from InfluxDB 1.x or 2.x to InfluxDB 3.x, InfluxData recommends adopting SQL as your query language. Refer to InfluxData’s migration guide for help transitioning your data and queries.

If you’re unsure which InfluxDB product you’re using, refer to InfluxData’s InfluxDB product detection tool for guidance.

Add the InfluxDB data source

Complete the following steps to set up a new InfluxDB data source:

Click Connections in the left-side menu.
Click Add new connection.
Type InfluxDB in the search bar.
Select the InfluxDB data source.
Click Add new data source in the upper right.

Note
Complete the required connection settings and click Save & test before you rename the data source. If you rename a new data source before saving it, Grafana validates the entire configuration and returns an error because the URL field is still empty.

Grafana opens the Settings tab where you configure the data source. A sidebar on the left displays navigation links to each configuration section:

URL and authentication
Database settings
Private data source connect (optional, Grafana Cloud only)
Save & test

Configuration options

The following sections describe the available configuration options.

First, configure the name of your connection.

Name - Sets the name you use to refer to the data source in panels and queries. Examples: InfluxDB-InfluxQL, InfluxDB_SQL.
Default - Toggle to set as the default data source.

URL and authentication

Use these settings to specify the InfluxDB instance the data source connects to.

URL - The HTTP protocol, IP address, and port of your InfluxDB API. The InfluxDB default API port is 8086. When you enter a URL, Grafana attempts to auto-detect your InfluxDB product based on URL patterns. Refer to InfluxDB detection for more information.
Product - Select the InfluxDB product you’re connecting to. The available query languages depend on your product selection.
Query language - Select the query language for your InfluxDB instance. This determines the connection details needed in Database settings. The available options are:
- Flux - Flux is a data scripting language developed by InfluxData that allows you to query, analyze, and act on data. Refer to Get started with Flux for guidance on using Flux.
- InfluxQL - SQL-like language for querying InfluxDB, with statements such as SELECT, FROM, WHERE, and GROUP BY that are familiar to SQL users.
- SQL - Native SQL language starting with InfluxDB v3.0. Refer to InfluxData’s SQL reference documentation for a list of supported statements, operators, and functions.

The following table shows which query languages are available for each InfluxDB product:

Product	Supported query languages
InfluxDB Cloud Dedicated	SQL, InfluxQL
InfluxDB Cloud Serverless	SQL, InfluxQL, Flux
InfluxDB Clustered	SQL, InfluxQL
InfluxDB Enterprise 1.x	InfluxQL, Flux
InfluxDB Enterprise 3.x	SQL, InfluxQL
InfluxDB Cloud (TSM)	InfluxQL, Flux
InfluxDB Cloud 1	InfluxQL
InfluxDB OSS 1.x	InfluxQL, Flux
InfluxDB OSS 2.x	InfluxQL, Flux
InfluxDB OSS 3.x	SQL, InfluxQL

Note
For InfluxQL only. Database + Retention Policy (DBRP) Mapping must be configured before data can be queried for the following products: InfluxDB OSS 1.x, InfluxDB OSS 2.x, InfluxDB Enterprise 1.x, InfluxDB Cloud (TSM), InfluxDB Cloud Serverless.

Refer to Manage DBRP Mappings for guidance on setting this up using the CLI or API.

Advanced HTTP settings

Toggle Advanced HTTP Settings to expand optional settings for more control over your data source.

Allowed cookies - Defines which cookies are forwarded to the data source. All other cookies are deleted by default.
Timeout - Sets the HTTP request timeout in seconds. If you don’t set a value, Grafana uses the timeout setting in the dataproxy section of the configuration file, which defaults to 30 seconds. Increase this value if complex queries or large result sets fail with timeout errors such as context deadline exceeded. Alert rule evaluations use the same timeout, so increasing it also gives alert queries more time to complete.

Custom HTTP headers

Click + Add header to add one or more HTTP headers. HTTP headers pass additional context and metadata about the request/response.

Header - Add a custom HTTP header. Select an option from the drop-down. Allows custom headers to be passed based on the needs of your InfluxDB instance.
Value - The value for the header.

Auth and TLS/SSL settings

Toggle Auth and TLS/SSL Settings to expand authentication and security options.

No Authentication - Make the data source available without authentication. Grafana recommends using some type of authentication method.
Basic auth - The most common authentication method. Use your InfluxDB instance username and password to authenticate.
Forward OAuth identity - Forward the OAuth access token (and also the OIDC ID token if available) of the user querying the data source.
With credentials - Toggle to enable credentials such as cookies or auth headers to be sent with cross-site requests.

TLS/SSL Certificates are encrypted and stored in the Grafana database.

TLS client auth - When enabled, add the Server name, Client cert and Client key. The client provides a certificate that the server validates to establish the client’s trusted identity. The client key encrypts the data between client and server.
- Server name - Name of the server. Example: server1.domain.com
- Client cert - Add the client certificate.
- Client key - Add the client key.
CA cert - Authenticate with a CA certificate. When enabled, follow the instructions of your CA (Certificate Authority) to download the certificate file.
Skip TLS verify - Toggle to bypass TLS certificate validation.

Database settings

Note
Setting the database for this data source does not deny access to other databases. The InfluxDB query syntax allows switching the database in the query. For example: SHOW MEASUREMENTS ON _internal or SELECT * FROM "_internal".."database" LIMIT 10

To support data isolation and security, make sure appropriate permissions are configured in InfluxDB.

Use these settings to specify the InfluxDB database your data source connects to. The required fields vary based on the query language selected in URL and authentication.

The following table shows which fields are required for each query language:

Setting	Flux	InfluxQL	SQL
Organization	✓
Default Bucket	✓
Database		✓	✓
User		✓
Password		✓
Token	✓		✓

Organization - Sets the InfluxDB organization used for Flux queries. Also used for the v.organization query macro.
Default Bucket - The InfluxDB bucket used for the v.defaultBucket macro in Flux queries.
Database - Sets the database name to query. Refer to View buckets in InfluxData’s documentation on how to locate the list of available buckets and their corresponding IDs.
User - The username used to sign in to InfluxDB.
Password - The password for the specified user. Used with InfluxQL queries.
Token - The authentication token used to query InfluxDB. Retrieve this from the Tokens page in the InfluxDB UI.

For SQL

The Database field maps to the InfluxDB 3.x database (equivalent to a bucket).
Use a database token with read access to the target database. For InfluxDB Cloud Serverless and Cloud Dedicated, generate a token from the InfluxDB management console or CLI.
SQL queries use the FlightSQL (gRPC) protocol. If your InfluxDB instance doesn’t use TLS, enable Insecure Connection in Advanced Database Settings.

For Flux

With InfluxDB 2.x products, use the InfluxDB authentication token.
For InfluxDB 1.8, the token is username:password.

Advanced database settings

Toggle Advanced Database Settings to expand optional settings that give you more control over the query experience.

Max series - Sets a limit on the maximum number of series or tables that Grafana processes. Set a lower limit to prevent system overload, or increase it if you have many small time series and need to display more of them. The default is 1000.

For Flux and InfluxQL

Min time interval - Sets the minimum time interval for auto group-by. Grafana recommends setting this to match the data write frequency. For example, if your data is written every minute, it’s recommended to set this interval to 1 minute, so that each group contains data from each new write. The default is 10s. Refer to Min time interval for format examples.

For InfluxQL

HTTP method - Sets the HTTP method used to query your data source. The POST method allows for larger queries that would return an error using the GET method. The default method is POST.
Autocomplete range - Sets a time range limit for the query editor autocomplete to reduce the execution time of tag filter queries. Tags not present within the defined time range are filtered out. For example, setting the value to 12h includes only tag keys and values from the past 12 hours. This feature is recommended for very large databases, where significant performance improvements can be observed.

For SQL

Insecure Connection - Toggle to disable gRPC TLS security.

Private data source connect

For Grafana Cloud only. Private data source connect (PDC) allows you to establish a private, secured connection between a Grafana Cloud instance and data sources secured within a private network. For more information, refer to Private data source connect (PDC).

Click Manage private data source connect to go to your PDC connection page, where you’ll find your PDC configuration details.

Caution
When you use PDC, don’t set the InfluxDB URL to 127.0.0.1 or localhost. PDC tunnels traffic through a SOCKS proxy, which can’t resolve loopback addresses. Use the machine’s LAN IP address or a hostname that’s resolvable from the network where the PDC agent runs. Refer to PDC connection fails with “no such host” for more information.

PDC agent deployment, proxy configuration, and network and token management are covered in the PDC documentation, not here. Refer to Configure PDC for setup and Troubleshoot PDC issues for agent errors, log interpretation, and failure modes.

Save and test

After you have configured your connection settings, click Save & test to validate the data source connection.

A successful test returns one of the following messages depending on your query language:

Query language	Success message
Flux	`datasource is working. X buckets found`
InfluxQL	`datasource is working. X measurements found`
SQL	`OK`

If the test fails, refer to Troubleshoot InfluxDB data source issues for help resolving common connection and authentication errors.

Min time interval

The Min time interval setting defines a lower limit for the auto group-by time interval.

This value must be formatted as a number followed by a valid time identifier:

Identifier	Description
`y`	year
`M`	month
`w`	week
`d`	day
`h`	hour
`m`	minute
`s`	second
`ms`	millisecond

You can also override this setting in a dashboard panel under its data source options.

Provision the InfluxDB data source

You can define and configure the data source in YAML files as part of the Grafana provisioning system. For more information about provisioning, and for available configuration options, refer to Provision Grafana.

Note
The database field is deprecated. Grafana recommends using the dbName field in jsonData. There is no need to change existing provisioning settings.

Provisioning examples

Provisioning differs based on query language.

InfluxDB 1.x example:

apiVersion: 1

datasources:
  - name: InfluxDB_v1
    type: influxdb
    access: proxy
    user: grafana
    url: http://localhost:8086
    jsonData:
      dbName: site
      httpMode: GET
    secureJsonData:
      password: grafana

InfluxDB 2.x for Flux example:

apiVersion: 1

datasources:
  - name: InfluxDB_v2_Flux
    type: influxdb
    access: proxy
    url: http://localhost:8086
    jsonData:
      version: Flux
      organization: organization
      defaultBucket: bucket
      tlsSkipVerify: true
    secureJsonData:
      token: token

InfluxDB 2.x for InfluxQL example:

apiVersion: 1

datasources:
  - name: InfluxDB_v2_InfluxQL
    type: influxdb
    access: proxy
    url: http://localhost:8086
    jsonData:
      dbName: site
      httpHeaderName1: 'Authorization'
    secureJsonData:
      httpHeaderValue1: 'Token <token>'

InfluxDB 3.x for SQL example:

apiVersion: 1

datasources:
  - name: InfluxDB_v3_SQL
    type: influxdb
    access: proxy
    url: http://localhost:8086
    jsonData:
      version: SQL
      dbName: site
      httpMode: POST
      insecureGrpc: false
    secureJsonData:
      token: '<api-token>'

Configure the data source with Terraform

You can configure the InfluxDB data source using the Grafana Terraform provider.

Terraform prerequisites

Before you begin, you need:

Terraform installed
Grafana Terraform provider configured with appropriate credentials
For Grafana Cloud: A Cloud Access Policy token with data source permissions

Provider configuration

Configure the Grafana provider to connect to your Grafana instance:

terraform {
  required_providers {
    grafana = {
      source  = "grafana/grafana"
      version = ">= 2.0.0"
    }
  }
}

# For Grafana Cloud
provider "grafana" {
  url  = "<YOUR_GRAFANA_CLOUD_STACK_URL>"
  auth = "<YOUR_SERVICE_ACCOUNT_TOKEN>"
}

# For self-hosted Grafana
# provider "grafana" {
#   url  = "http://localhost:3000"
#   auth = "<API_KEY_OR_SERVICE_ACCOUNT_TOKEN>"
# }

Terraform examples

The following examples show how to configure the InfluxDB data source for each query language.

InfluxDB 2.x with Flux:

resource "grafana_data_source" "influxdb_flux" {
  type = "influxdb"
  name = "InfluxDB_Flux"
  url  = "http://localhost:8086"

  json_data_encoded = jsonencode({
    version       = "Flux"
    organization  = "<ORGANIZATION>"
    defaultBucket = "<DEFAULT_BUCKET>"
    tlsSkipVerify = false
  })

  secure_json_data_encoded = jsonencode({
    token = "<API_TOKEN>"
  })
}

InfluxDB 1.x with InfluxQL:

resource "grafana_data_source" "influxdb_influxql" {
  type = "influxdb"
  name = "InfluxDB_InfluxQL"
  url  = "http://localhost:8086"

  basic_auth_enabled  = true
  basic_auth_username = "<USERNAME>"

  json_data_encoded = jsonencode({
    dbName   = "<DATABASE>"
    httpMode = "POST"
  })

  secure_json_data_encoded = jsonencode({
    basicAuthPassword = "<PASSWORD>"
  })
}

InfluxDB 2.x with InfluxQL (token auth):

resource "grafana_data_source" "influxdb_v2_influxql" {
  type = "influxdb"
  name = "InfluxDB_v2_InfluxQL"
  url  = "http://localhost:8086"

  json_data_encoded = jsonencode({
    dbName          = "<DATABASE>"
    httpHeaderName1 = "Authorization"
  })

  secure_json_data_encoded = jsonencode({
    httpHeaderValue1 = "Token <API_TOKEN>"
  })
}

InfluxDB 3.x with SQL:

resource "grafana_data_source" "influxdb_sql" {
  type = "influxdb"
  name = "InfluxDB_SQL"
  url  = "http://localhost:8086"

  json_data_encoded = jsonencode({
    version      = "SQL"
    dbName       = "<DATABASE>"
    httpMode     = "POST"
    insecureGrpc = false
  })

  secure_json_data_encoded = jsonencode({
    token = "<API_TOKEN>"
  })
}

For more information about the Grafana Terraform provider, refer to the Terraform provider documentation.

InfluxDB query editor

Tue, 27 Oct 2026 11:15:42 +0000

InfluxDB query editor

The InfluxDB query editor helps you build and run queries against your InfluxDB data source. You can access it from the Explore page or from any dashboard panel by clicking the ellipsis in the upper right of the panel and selecting Edit.

The editor supports three query languages: SQL, InfluxQL, and Flux. Each has its own editing experience and macro system. SQL and InfluxQL provide both a visual builder mode and a code editing mode, while Flux provides a code editor only. You can also use the query editor to retrieve log data.

For general information about Grafana query editors, refer to Query and transform data.

To compare InfluxQL and SQL queries for the same data, explore this demo dashboard on Grafana Play:

Give it a try using Grafana Play

With Grafana Play, you can explore and see how it works, learning from practical examples to accelerate your development. This feature can be seen on Influx: Bar Charts and Time Series using Mixed queries.

Try it

Before you begin

Ensure you have configured the InfluxDB data source.
Verify your credentials have appropriate permissions to query the target database or bucket.

Key concepts

If you’re new to InfluxDB, these terms are used throughout the query editor:

Term	Description
Measurement	A logical grouping of fields, tags, and timestamps, similar to a table in a relational database.
Field	A column in a measurement that stores the actual data values (numbers, strings, Boolean values).
Tag	A column used for metadata and indexing. Tags are indexed and optimized for filtering.
Retention policy	An InfluxDB 1.x setting that controls how long data is stored before automatic deletion.
Bucket	An InfluxDB 2.x and 3.x storage location that combines a database and retention policy.

Choose a query editor

The InfluxDB data source has three query editors, each corresponding to the query language selected in the data source configuration:

Editor options vary based on query language.

InfluxQL query editor

The InfluxQL query editor helps you select metrics and tags to create InfluxQL queries. There are two modes: visual editor mode and raw query mode. To switch between the two modes click the pencil icon in the upper right.

Visual query editor mode contains the following components:

FROM - Select a measurement to query.
WHERE - Select filters by clicking the + sign. You can enter regular expressions or use the text input for regular expression tag values.
SELECT - Select fields and functions from the drop-down. You can add multiple fields and functions by clicking the + sign.
GROUP BY - Select a tag from the drop-down menu.
TIMEZONE - Optional Group data by a specific timezone.
ORDER BY TIME - Sort data by time in either ascending or descending order.
LIMIT - Optional Limits the number of rows returned by the query.
SLIMIT - Optional Limits the number of series returned by the query. Refer to SLIMIT clause for more information.
FORMAT AS - Select a format option from the drop-down menu: time series, table, or logs.
ALIAS - Add an alias. Refer to Alias patterns for more information.

Raw query editor mode

You can write raw InfluxQL queries by switching to raw query mode. Click the pencil in the upper right of the query editor to switch modes. When you switch to visual editor mode, any changes made in raw query mode are lost.

If you use raw query mode, your query must include WHERE $timeFilter. You should also provide a group by time and an aggregation function. Otherwise, InfluxDB may return hundreds of thousands of data points, potentially causing your browser to hang.

Match by regular expressions

You can enter regular expressions for metric names or tag filter values. Wrap the regular expression pattern in forward slashes (/), as shown in this example: /measurement/.

Grafana automatically adjusts the filter tag condition to use the InfluxDB regular expression match condition operator (=~).

Field and aggregation functions

In the SELECT row, you can specify which fields and functions to use.

If you group by time you must use an aggregation function. Certain functions such as derivative also require an aggregation function.

The query editor input generates an InfluxDB SELECT clause. For example:

SELECT derivative(mean("value"), 10s) / 10 AS "REQ/s"
FROM....

You can also use a * in a SELECT statement to select all fields.

SELECT * FROM <measurement_name>

GROUP BY results

To group results by a tag, specify the tag in the GROUP BY row:

Click the + sign in the GROUP BY row.
Select a tag from the drop-down.

You can GROUP BY multiple options.

To remove a GROUP BY option click the X icon next to the option.

Alias patterns

Alias pattern	Replaced with
`$m`	Measurement name.
`$measurement`	Measurement name.
`$1` - `$9`	Part of measurement name (if you separate your measurement name with dots).
`$col`	Column name.
`$tag_exampletag`	The value of the `exampletag` tag. The syntax is `$tag_yourTagName` and must start with `$tag_`. To use your tag as an alias in the ALIAS BY field, you must use the tag to group by in the query.

You can also use the [[tag_hostname]] pattern replacement syntax.

For example, entering the value Host: [[tag_hostname]] in the ALIAS BY field replaces it with the hostname tag value for each legend value.

An example legend value is Host: server1.

SQL query editor

Grafana supports the SQL query language for InfluxDB 3.x and newer cloud products (Cloud Serverless, Cloud Dedicated, Clustered). SQL is InfluxData’s recommended query language for new deployments.

The SQL query editor provides two modes:

Builder mode - A visual query builder that helps you construct SQL queries by selecting tables, columns, filters, and aggregations from drop-down menus. This mode is useful for building queries without writing SQL directly.
Code mode - A text editor for writing raw SQL queries with autocomplete and syntax highlighting. Switch between modes using the toggle at the top of the query editor.

SQL queries connect to InfluxDB using the FlightSQL (gRPC) protocol, which provides high-performance data transfer for large result sets.

Format output

The SQL query editor supports two output formats:

Time series (default) - Returns data as time-series frames. The query must include a timestamp column.
Table - Returns data as a table frame, useful for non-time-series queries or when you want to display raw results.

Select the format from the Format drop-down in the query editor.

Macros

You can use macros in your query to automatically substitute them with values from the Grafana context.

Macro example	Replaced with
`$__timeFrom`	The start of the currently active time selection, such as `cast('2020-06-11T13:31:00Z' as timestamp)`.
`$__timeTo`	The end of the currently active time selection, such as `cast('2020-06-11T14:31:00Z' as timestamp)`.
`$__timeFilter(<column>)`	A time range filter applied to the specified column. Expands to `<column> >= $__timeFrom AND <column> <= $__timeTo`.
`$__interval`	An interval string that corresponds to the Grafana calculated interval based on the time range of the active time selection, such as `interval '5 second'`.
`$__dateBin(<column>)`	Applies the `date_bin` function using `$__interval`. Column must be a timestamp.
`$__dateBinAlias(<column>)`	Applies the `date_bin` function with a `_binned` suffix alias. Column must be a timestamp.
`$__timeGroup(<column>)`	Groups results by a time interval using `date_bin()` with `$__interval`. Column must be a timestamp.
`$__timeGroupAlias(<column>)`	Groups results by a time interval using `date_bin()` with `$__interval` and adds a `_binned` suffix alias. Column must be a timestamp.

SQL query examples

Basic time-series query:

SELECT time, usage_system, usage_user
FROM cpu
WHERE $__timeFilter(time)
ORDER BY time

Aggregated time-series query with date_bin:

SELECT
  $__dateBin(time) AS time,
  mean(usage_system) AS avg_system,
  mean(usage_user) AS avg_user
FROM cpu
WHERE $__timeFilter(time)
GROUP BY $__dateBin(time)
ORDER BY time

Using JOINs across tables:

SQL supports JOINs, which aren’t available in InfluxQL or Flux:

SELECT
  c.time,
  c.usage_system,
  m.used_percent AS mem_used
FROM cpu c
INNER JOIN mem m ON c.time = m.time AND c.host = m.host
WHERE $__timeFilter(c.time)
ORDER BY c.time

Filtering with WHERE clauses:

SELECT $__dateBin(time) AS time, mean(usage_system) AS avg_system
FROM cpu
WHERE $__timeFilter(time)
  AND host = 'server01'
  AND cpu = 'cpu-total'
GROUP BY $__dateBin(time)
ORDER BY time

For the full list of supported SQL statements, operators, and functions, refer to InfluxData’s SQL reference documentation.

Flux query editor

Grafana supports Flux when running InfluxDB v1.8 and higher. If your data source is configured for Flux, you can use the Flux in the query editor, which serves as a text editor for raw Flux queries with macro support.

For more information and connection details, refer to InfluxDB 1.8 API compatibility.

Use macros

You can enter macros in the query to replace them with values from the Grafana context.

Macros support copying and pasting from InfluxData Chronograf.

Macro example	Replaced with
`v.timeRangeStart`	The start of the currently active time selection, such as `2020-06-11T13:31:00Z`.
`v.timeRangeStop`	The end of the currently active time selection, such as `2020-06-11T14:31:00Z`.
`v.windowPeriod`	An interval string compatible with Flux that corresponds to the Grafana calculated interval based on the time range of the active time selection, such as `5s`.
`v.defaultBucket`	The Default Bucket value from the data source configuration.
`v.organization`	The data source configuration’s Organization setting.

For example, consider the following Flux query:

from(bucket: v.defaultBucket)
  |> range(start: v.timeRangeStart, stop: v.timeRangeStop)
  |> filter(fn: (r) => r["_measurement"] == "cpu" or r["_measurement"] == "swap")
  |> filter(fn: (r) => r["_field"] == "usage_system" or r["_field"] == "free")
  |> aggregateWindow(every: v.windowPeriod, fn: mean)
  |> yield(name: "mean")

Grafana interpolates this Flux query into the following and sends it to InfluxDB, with the interval and time period values changing according to the active time selection:

from(bucket: "grafana")
  |> range(start: 2020-06-11T13:59:07Z, stop: 2020-06-11T14:59:07Z)
  |> filter(fn: (r) => r["_measurement"] == "cpu" or r["_measurement"] == "swap")
  |> filter(fn: (r) => r["_field"] == "usage_system" or r["_field"] == "free")
  |> aggregateWindow(every: 2s, fn: mean)
  |> yield(name: "mean")

To view the interpolated version of a query with the Query inspector, refer to Panel Inspector.

Query logs

You can query and display log data from InfluxDB in Explore and in the dashboard Logs panel.

InfluxQL: Select an InfluxDB data source in the query editor. Under the Select measurement field next to the FROM section, choose a measurement containing your log data, then choose the appropriate fields that display the log message. Add any additional filters by clicking the + sign next to the WHERE field. Set FORMAT AS to Logs.

SQL: Write a SQL query that returns a timestamp column and a text column containing the log message. Set the Format to Table. For example:

SELECT time, message, level, host
FROM syslog
WHERE $__timeFilter(time)
ORDER BY time DESC

Flux: Use a Flux query with the _value field containing the log message.

After InfluxDB returns the results, the log panel displays log rows along with a bar chart. The x-axis represents time, while the y-axis shows the frequency or count.

Next steps

Use template variables for dynamic dashboards.
Set up annotations to overlay events on your graphs.
Create alert rules based on your InfluxDB queries.

InfluxDB template variables

Tue, 27 Oct 2026 11:15:42 +0000

InfluxDB template variables

Instead of hard-coding details such as server, application, and sensor names in metric queries, you can use variables. Grafana displays these variables in drop-down select boxes at the top of the dashboard to help you change the data displayed in your dashboard. Grafana refers to such variables as template variables.

For general information about variables, refer to Variables and Add and manage variables.

Before you begin

Configure the InfluxDB data source.
Understand Grafana template variables.

Supported variable types

Variable type	Supported
Query	Yes
Custom	Yes
Data source	Yes
Ad-hoc filter	Yes (InfluxQL only)

To switch a dashboard between InfluxDB instances, use a data source variable. Don’t use a query variable that returns data source names as a workaround. Query-based workarounds can break after Grafana upgrades because they depend on internal identifiers. Refer to Add a data source variable for details.

Where you can use variables

Variable support differs by query editor and mode:

Editor	Variable support
InfluxQL visual editor	Drop-downs include your template variables alongside values from your database.
InfluxQL raw mode	Full support.
SQL builder mode	Drop-downs list only tables and columns from your database. Switch to code mode to use variables.
SQL code mode	Full support. Press Ctrl+Space to show variable suggestions.
Flux code editor	Full support.

Create a query variable

By adding a query template variable, you can write an InfluxDB metadata exploration query. These queries return results such as measurement names, key names, and key values.

For more information, refer to Add a query variable.

InfluxQL query variable examples

To create a variable containing all values for the hostname tag, use the following query in the Query field:

SHOW TAG VALUES WITH KEY = "hostname"

You can fetch key names for a given measurement:

SHOW TAG KEYS [FROM <measurement_name>]

You can list available measurements:

SHOW MEASUREMENTS

Flux query variable examples

For Flux-configured data sources, write a Flux query that returns a single column of values:

import "influxdata/influxdb/schema"
schema.tagValues(bucket: v.defaultBucket, tag: "hostname")

SQL query variable examples

For SQL-configured data sources (InfluxDB 3.x), write an SQL query that returns a single column of values:

SELECT DISTINCT hostname FROM cpu

You can list available tables:

SHOW TABLES

You can list columns in a specific table:

SHOW COLUMNS FROM cpu

Scope variables to the dashboard time range

By default, metadata queries such as SHOW TAG VALUES return values from the entire retention period, not just the dashboard time range. If a host or sensor stopped reporting long ago, its values still appear in the variable drop-down as long as they exist within retention.

To limit variable results to the dashboard time range:

Include a time condition in the variable query. Variable queries interpolate the same time macros as regular queries: $timeFilter for InfluxQL, $__timeFilter(<column>) for SQL, and v.timeRangeStart and v.timeRangeStop for Flux.
Set the variable’s Refresh option to On time range change so the values update when the dashboard time range changes.

InfluxQL example:

SHOW TAG VALUES WITH KEY = "hostname" WHERE $timeFilter

SQL example:

SELECT DISTINCT hostname FROM cpu WHERE $__timeFilter(time)

Chain or nest variables

You can create nested variables, sometimes called chained variables.

For example, if you have a variable named region, you can configure the hosts variable to display only hosts from the selected region.

InfluxQL:

SHOW TAG VALUES WITH KEY = "hostname"  WHERE region = '$region'

SQL:

SELECT DISTINCT hostname FROM cpu WHERE region = '$region'

If you have a variable containing key names, you can use it in a GROUP BY clause. This allows you to adjust the grouping by selecting from the variable list at the top of the dashboard.

Use filters

InfluxDB supports the use of filters for InfluxQL. They allow you to define multiple key/value filters, which Grafana automatically applies to all your InfluxDB queries. Filters also support expressions.

To add filters:

Navigate to the dashboard you want to update and click Edit.
Click the Add new element icon (blue plus sign).
Click Filter and Group by.
Enter a Name for the filter.
Select an option in the Display drop-down list to control where on the dashboard the filter is displayed.
Select your InfluxDB data source in the Data source drop-down list.

For more information, refer to the Filter and Group by documentation.

Choose a variable syntax

The InfluxDB data source supports two variable syntaxes for use in the Query field:

$<varname> - Use this syntax for standalone variable references. It doesn’t allow you to use a variable in the middle of a word or expression.
${varname} - Use this syntax when you want to interpolate a variable in the middle of an expression.

InfluxQL examples:

SELECT mean("value") FROM "logins" WHERE "hostname" =~ /^$host$/ AND $timeFilter GROUP BY time($__interval), "hostname"

SELECT mean("value") FROM "logins" WHERE "hostname" =~ /^${host}$/ AND $timeFilter GROUP BY time($__interval), "hostname"

When you enable the Multi-value or Include all value options with InfluxQL, Grafana converts the labels from plain text to a regular expression-compatible string, so you must use =~ instead of = and wrap the variable in a regular expression such as /^$host$/.

For example, if $host is a multi-value variable and you select server1 and server2, Grafana joins the values with |, wraps them in parentheses, and escapes any special characters. The interpolated query looks like this:

SELECT mean("value") FROM "logins" WHERE "hostname" =~ /^(server1|server2)$/ AND $timeFilter GROUP BY time($__interval), "hostname"

SQL examples:

SELECT $__dateBin(time), mean(usage_system) FROM cpu WHERE $__timeFilter(time) AND host = '$host' GROUP BY $__dateBin(time)

SELECT $__dateBin(time), mean(usage_system) FROM cpu WHERE $__timeFilter(time) AND host IN ($host) GROUP BY $__dateBin(time)

When you enable the Multi-value option with SQL, use the IN operator instead of = to match multiple values.

Prevent unwanted value escaping

When you use a variable inside a regular expression, or when the variable is multi-value, Grafana escapes special characters in the values so the query remains valid. If you need the literal, unmodified value instead, use the raw format option:

SELECT mean("value") FROM "requests" WHERE "path" = '${path:raw}' AND $timeFilter GROUP BY time($__interval)

This is useful for custom variables whose values intentionally contain characters that Grafana would otherwise escape. For all available format options, refer to Advanced variable format options.

Templated dashboard example

To view an example of a templated dashboard, refer to this InfluxDB example dashboard.

InfluxDB annotations

Tue, 27 Oct 2026 11:15:42 +0000

InfluxDB annotations

Annotations overlay event data on your dashboard graphs, helping you correlate events with metrics. You can use InfluxDB as a data source for annotations to display events such as deployments, alerts, or other significant occurrences on your visualizations.

For general information about annotations, refer to Annotate visualizations.

Before you begin

Before creating InfluxDB annotations, ensure you have:

An InfluxDB data source configured in Grafana
Data in InfluxDB containing event information with timestamp fields
Read access to the InfluxDB database or bucket containing your events

Create an annotation query

To add an InfluxDB annotation to your dashboard:

Navigate to the dashboard you want to update and click Edit.
Click the Add new element icon (blue plus sign).
Click Annotation query.
Enter a name for the annotation query.
If you don’t want to use the annotation query right away, clear the Enabled checkbox.
Select a color for the annotation event markers.
Select an option in the Show annotation controls in drop-down list to control where on the dashboard the annotation is displayed.
Select an option in the Show in drop-down list to control the panels in which the annotation is displayed.
Click Open query editor to open the Annotation Query dialog box.
Select your InfluxDB data source from the Data source drop-down list.
Configure the annotation query and field mappings.
(Optional) Click Test annotation query to ensure that the query is working properly.
Click Close when you’ve completed the query setup.
Click Save.
(Optional) Enter a description of the changes you’ve made.
Click Save.
Click Exit edit.

InfluxQL annotations

For InfluxQL-configured data sources, write an InfluxQL query in the InfluxQL Query field. Your query must include WHERE $timeFilter to scope the results to the dashboard’s time range.

Field mappings

Field mappings tell Grafana which InfluxDB columns contain the annotation data. If your query returns only one column, you don’t need to enter anything in the field mapping fields.

Field	Description
Text	The column containing the annotation description displayed when you hover over the annotation.
Tags	The column containing tags for the annotation. The value can be a comma-separated string. Tags help categorize and filter annotations.
TimeEnd	The column containing an end time for range annotations. Range annotations display as a shaded region on the graph instead of a single vertical line.

InfluxQL annotation query example

The following query retrieves deployment events and displays them as annotations:

SELECT title, description
FROM events
WHERE $timeFilter
ORDER BY time ASC

Range annotation example

To display events with duration as shaded regions:

SELECT description, tags, end_time
FROM maintenance_windows
WHERE $timeFilter
ORDER BY time ASC

Configure the field mappings as follows:

Text: description
Tags: tags
TimeEnd: end_time

Flux annotations

For Flux-configured data sources, annotations use the standard Flux query editor. Write a Flux query that returns data frames with time, text, and optional tag fields.

Flux annotation query example

from(bucket: "events")
  |> range(start: v.timeRangeStart, stop: v.timeRangeStop)
  |> filter(fn: (r) => r["_measurement"] == "deployments")
  |> pivot(rowKey: ["_time"], columnKey: ["_field"], valueColumn: "_value")

Grafana processes the resulting data frames as annotation events. Ensure the query returns a _time column and at least one text column.

SQL annotations

SQL-configured data sources (InfluxDB 3.x) use the standard Grafana annotation query editor. Write an SQL query that returns a time column and at least one text column. Use the $__timeFilter(time) macro to scope results to the dashboard time range.

SQL annotation query example

SELECT time, title, description
FROM events
WHERE $__timeFilter(time)
ORDER BY time ASC

SQL range annotation example

To display events with duration as shaded regions, return both a start time and an end time:

SELECT time, end_time, description, tags
FROM maintenance_windows
WHERE $__timeFilter(time)
ORDER BY time ASC

Configure the field mappings:

Text: description
Tags: tags
TimeEnd: end_time

Use template variables in annotations

You can use template variables in your annotation queries to filter annotations based on dashboard variable selections. For example:

SELECT title, description
FROM events
WHERE $timeFilter AND environment = '$environment'
ORDER BY time ASC

If your annotations aren’t appearing or you encounter errors, refer to Troubleshoot InfluxDB data source issues.

InfluxDB alerting

Tue, 27 Oct 2026 11:15:42 +0000

InfluxDB alerting

You can use Grafana Alerting with InfluxDB to create alerts based on your time-series data. This allows you to monitor metrics, detect anomalies, and receive notifications when specific conditions are met.

For general information about Grafana Alerting, refer to Grafana Alerting.

Before you begin

Before creating alerts with InfluxDB, ensure you have:

An InfluxDB data source configured in Grafana
Appropriate permissions to create alert rules
Understanding of the metrics you want to monitor

Supported query types

InfluxDB alerting supports all three query languages: InfluxQL, SQL, and Flux. Queries must return time-series data for Grafana to evaluate values over time and trigger alerts when thresholds are crossed.

Query language compatibility

Query language	Alerting support	Notes
InfluxQL	Yes	Use aggregation functions with GROUP BY time.
Flux	Yes	Use `aggregateWindow()` for time-based aggregation.
SQL	Yes	Use `$__timeFilter` and `$__dateBin` macros for time filtering.

Create an alert rule

To create an alert rule using InfluxDB:

Navigate to Alerting > Alert rules.
Click New alert rule.
Enter a name for the alert rule.
Select your InfluxDB data source.
Build your query using the query editor.
Configure the alert condition (for example, when the average is above a threshold).
Set the evaluation interval and pending period.
Configure notifications and labels.
Click Save rule.

For detailed instructions, refer to Create a Grafana-managed alert rule.

Example alert queries

The following examples show common alerting scenarios with InfluxDB.

InfluxQL: Alert on high CPU usage

Monitor CPU usage and alert when it exceeds a threshold:

Query: Select the cpu measurement with mean("usage_system") as the aggregation.
GROUP BY: time($__interval)
Condition: When mean is above 90.

In raw query mode:

SELECT mean("usage_system") FROM "cpu" WHERE $timeFilter GROUP BY time($__interval) fill(null)

Flux: Alert on memory pressure

Monitor memory usage with a Flux query:

from(bucket: "telegraf")
  |> range(start: v.timeRangeStart, stop: v.timeRangeStop)
  |> filter(fn: (r) => r["_measurement"] == "mem")
  |> filter(fn: (r) => r["_field"] == "used_percent")
  |> aggregateWindow(every: v.windowPeriod, fn: mean)
  |> yield(name: "mean")

Set the condition to alert when the mean value exceeds 85.

SQL: Alert on disk usage

Monitor disk usage with an SQL query:

SELECT $__dateBin(time), mean(used_percent)
FROM disk
WHERE $__timeFilter(time)
GROUP BY $__dateBin(time)

Set the condition to alert when the mean value exceeds 80.

Limitations

When using InfluxDB with Grafana Alerting, be aware of the following limitations:

Template variables not supported

Alert queries can’t contain template variables. Grafana evaluates alert rules on the backend without dashboard context, so variables like $hostname or $region aren’t resolved.

If your dashboard query uses template variables, create a separate query for alerting with hard-coded values.

Query complexity

Complex queries with many nested functions or large result sets may timeout or fail to evaluate. Simplify queries for alerting by:

Reducing the time range
Using appropriate aggregation intervals
Adding filters to limit the data scanned

Handle transient errors and timeouts

Brief InfluxDB latency spikes or network interruptions can cause alert rule evaluations to fail. By default, a failed evaluation moves the rule into an error state, which can trigger a large number of spurious notifications at once even though your data is healthy.

To make alert rules resilient to transient errors:

In the alert rule settings, expand Configure no data and error handling and set Alert state if execution error or timeout to Keep Last State. The rule keeps its previous state through brief evaluation failures instead of firing an error alert.
Set a Pending period so the alert condition must be met for a sustained period across multiple evaluations before the alert fires.
If evaluations fail because queries run out of time, increase the data source timeout. Refer to Advanced HTTP settings for details.
Simplify or narrow alert queries so they complete well within the timeout. Refer to Query complexity for guidance.

For more information about error state handling, refer to No data and error handling.

Best practices

Follow these best practices when creating InfluxDB alerts:

Use specific filters: Add WHERE clauses or Flux filters to focus on relevant data and improve query performance.
Choose appropriate intervals: Match the GROUP BY time interval to your evaluation frequency.
Test queries first: Verify your query returns expected results in Explore before creating an alert.
Set realistic thresholds: Base alert thresholds on historical data patterns.
Use meaningful names: Give alert rules descriptive names that indicate what they monitor.

If you encounter errors when creating or evaluating alert rules, refer to Troubleshoot InfluxDB data source issues.

Troubleshoot InfluxDB data source issues

Tue, 27 Oct 2026 11:15:42 +0000

Troubleshoot InfluxDB data source issues

This document provides solutions to common issues you may encounter when configuring or using the InfluxDB data source. Issues are organized to follow the typical setup and usage workflow. For configuration instructions, refer to Configure the InfluxDB data source.

Connection errors

The following errors occur when Grafana can’t establish or maintain a connection to InfluxDB.

“Plugin health check failed” or “An error occurred within the plugin”

Symptoms:

All panels using InfluxDB return “An error occurred within the plugin”
Adding a new InfluxDB data source fails with “Plugin health check failed”
Connection settings appear blank in the UI

Possible causes and solutions:

Cause	Solution
Platform outage	If all InfluxDB panels fail at the same time, check the Grafana Cloud status page for active incidents before investigating your own configuration. The issue may be a transient platform problem that resolves without customer-side action.
Authentication failure	Check the Grafana server logs for auth-related errors. Verify your credentials haven’t expired or been rotated.
Transient network issue	The error may self-resolve. Wait a few minutes and retry Save & test. If the issue persists, check network connectivity between Grafana and InfluxDB.

Failed to connect to InfluxDB

Error message: error performing influxQL query or error performing flux query or error performing sql query

Cause: Grafana can’t establish a network connection to the InfluxDB server.

Solution:

Verify that the InfluxDB URL is correct in the data source configuration.
Check that InfluxDB is running and accessible from the Grafana server.
Ensure the URL includes the protocol (http:// or https://).
Verify the port is correct (the InfluxDB default API port is 8086).
Ensure there are no firewall rules blocking the connection.
For Grafana Cloud, ensure you have configured Private data source connect if your InfluxDB instance is not publicly accessible.

PDC connection fails with “no such host”

Error message: socks connect tcp ... -> influxdb.host:8086: dial tcp: lookup ... no such host

Cause: When using Private data source connect (PDC), the InfluxDB URL can’t be resolved through the SOCKS proxy tunnel.

Solution:

Don’t use 127.0.0.1 or localhost as the InfluxDB URL. PDC tunnels traffic over a SOCKS proxy, which can’t resolve loopback addresses.
Use the machine’s LAN IP address or a resolvable hostname instead.
Verify the hostname is resolvable from the network where the PDC agent is running.
If the error appeared suddenly without configuration changes, check the Grafana Cloud status page for active incidents.

PDC connection stops working after certificate renewal fails

Symptoms:

A previously working PDC-connected data source stops working
The PDC agent logs show errors renewing or signing the SSH certificate
Queries fail with SOCKS proxy connection errors

Cause: The PDC agent uses a Grafana Cloud API token to periodically renew its SSH certificate. If the token is incorrect, has expired, or has been deleted, certificate renewal fails and the connection stops working when the current certificate expires.

Solution:

Check the PDC agent logs for authentication or certificate signing errors.
Verify the API token in the PDC agent configuration is valid. If the token has expired or been deleted, generate a new one from your PDC connection page in Grafana Cloud and update the agent configuration.
Restart the PDC agent after updating the token.
Refer to Troubleshoot PDC issues for agent error codes, log interpretation, and token management guidance.

TLS certificate errors

Error message: x509: certificate signed by unknown authority or similar TLS verification errors

Cause: InfluxDB presents a TLS certificate that isn’t signed by a certificate authority (CA) that the Grafana server trusts. This is common with self-signed certificates and internal corporate certificate authorities. TLS verification applies end to end, so this error also occurs when you connect through PDC.

Solution:

The InfluxDB data source supports TLS configuration for each data source instance. In the data source settings, expand Auth and TLS/SSL Settings, enable CA cert, and paste your CA certificate. Refer to Auth and TLS/SSL settings for details.
If your InfluxDB server requires client certificates, enable TLS client auth and provide the server name, client certificate, and client key.
As a last resort, you can enable Skip TLS verify to bypass certificate validation. Grafana doesn’t recommend this for production use because it disables protection against man-in-the-middle attacks.

Request timed out

Error message: context deadline exceeded or request timeout or dial tcp <IP>:<port>: i/o timeout

Cause: The connection to InfluxDB timed out before receiving a response. This is common after Grafana upgrades when infrastructure changes (such as database host migrations) happen at the same time.

Solution:

Verify network connectivity from the Grafana server to your InfluxDB endpoint. Check DNS resolution, firewall rules, and port access.
Confirm the InfluxDB host IP address or hostname hasn’t changed. This is especially important after infrastructure migrations or Grafana upgrades.
Check the network latency between Grafana and InfluxDB.
Verify that InfluxDB is not overloaded or experiencing performance issues.
Increase the timeout setting in the data source configuration under Advanced HTTP Settings.
Reduce the time range or complexity of your query.

Authentication errors

The following errors occur when there are issues with authentication credentials or permissions.

Unauthorized (401)

Error message: “401 Unauthorized” or “authorization failed”

Cause: The authentication credentials are invalid or missing. Transient network issues can also surface as authentication errors even when your credentials are valid.

Solution:

If the error is intermittent or appeared without a configuration change, wait a few minutes and retry Save & test to rule out a transient network issue before rotating credentials.
Verify that the token or password is correct in the data source configuration.
For Flux and SQL, ensure the token has not expired.
For InfluxQL with InfluxDB 2.x, verify the token is set as an Authorization header with the value Token <your-token>.
For InfluxDB 1.x, verify the username and password are correct.
Check that the token has the required permissions to access the specified bucket or database.

Forbidden (403)

Error message: “403 Forbidden” or “access denied”

Cause: The authenticated user or token doesn’t have permission to access the requested resource.

Solution:

Verify the token has read access to the specified bucket or database.
Check the token’s permissions in the InfluxDB UI under API Tokens.
Ensure the organization ID is correct for Flux queries.
For InfluxQL with InfluxDB 2.x, verify the DBRP mapping is configured correctly.

Configuration errors

The following errors occur when the data source is not configured correctly.

URL not configured

Error message: missing URL from datasource configuration

Cause: The data source URL field is empty.

Solution:

Open the data source configuration in Grafana.
Enter the full URL of your InfluxDB instance in the URL field, including the protocol and port (for example, http://localhost:8086).
Click Save & test to verify the connection.

Unknown influx version

Error message: “unknown influx version”

Cause: The query language is not properly configured in the data source settings.

Solution:

Open the data source configuration in Grafana.
Verify that a valid query language is selected: Flux, InfluxQL, or SQL.
Match the query language to your InfluxDB version:

InfluxDB version	Recommended query language	Notes
1.x	InfluxQL	Flux is available from 1.8+ but InfluxQL is the primary language.
2.x (OSS/Cloud)	Flux	InfluxQL is also available via the v1 compatibility API, but requires DBRP mapping.
3.x / Cloud Dedicated / Cloud Serverless	SQL or InfluxQL	Flux is not supported on InfluxDB 3.x.

Each query language uses a different API endpoint. If you select the wrong language for your InfluxDB version, health checks and queries fail.

Invalid data source info received

Error message: invalid data source info received

Cause: The data source configuration is incomplete or corrupted.

Solution:

Delete and recreate the data source.
Ensure all required fields are populated based on your query language:
- Flux: URL, Organization, Token, Default Bucket
- InfluxQL: URL, Database, User, Password
- SQL: URL, Database, Token

DBRP mapping required

Error message: “database not found” or queries return no data with InfluxQL on InfluxDB 2.x

Cause: InfluxQL queries on InfluxDB 2.x require a Database and Retention Policy (DBRP) mapping.

Solution:

Create a DBRP mapping in InfluxDB using the CLI or API.
Refer to Manage DBRP Mappings for guidance.
Verify the database name in Grafana matches the DBRP mapping.

Browser access mode disabled

Error message: Direct browser access in the InfluxDB datasource is no longer available. Switch to server access mode.

Cause: The data source is configured for direct browser access, which is no longer supported.

Solution:

Open the data source configuration in Grafana.
Change the access mode to Server (default).
Click Save & test to verify the connection.

Content Security Policy (CSP) violation

Symptoms:

CSP violation errors in the browser console referencing the InfluxDB plugin
net::ERR_ABORTED on proxy requests
The InfluxDB plugin attempts direct browser-to-InfluxDB connections

Cause: You’re running an outdated version of Grafana. Browser access mode was removed in Grafana 9.2.0, and older versions may attempt direct browser connections that violate CSP policies. Current versions of the data source support only server (proxy) access, where the Grafana server sends all queries to InfluxDB and the browser never connects to InfluxDB directly.

Solution:

Upgrade to the latest stable Grafana release. The InfluxDB data source requires Grafana 12.3.0 or later.
After upgrading, verify the data source access mode is set to Server (default).

Health check errors

The following errors occur when clicking Save & test to validate the data source connection. Each query language uses a different health check query.

Flux health check errors

“error performing flux query”

Cause: The health check query buckets() failed to execute.

Solution:

Verify the InfluxDB URL is correct and reachable.
Check that the token is valid and has not expired.
Ensure the organization ID is correct.

“error reading buckets”

Cause: The buckets() query executed but returned an error.

Solution:

Verify the token has permission to list buckets.
Check that the organization ID matches the token’s organization.

“error getting flux query buckets”

Cause: The buckets() query executed without error but returned no data.

Solution:

Verify the token has permission to list buckets.
Check that the organization ID is correct.
Ensure InfluxDB is running and accessible.

InfluxQL health check errors

“error performing influxQL query”

Cause: The health check query SHOW MEASUREMENTS failed to execute.

Solution:

Verify the InfluxDB URL is correct and reachable.
Check the username and password (or token for InfluxDB 2.x).
Verify the database name exists.

“error reading influxDB”

Cause: The SHOW MEASUREMENTS query executed but returned an error.

Solution:

Verify the database name is correct.
Check that the user has permission to run SHOW MEASUREMENTS.
For InfluxDB 2.x, verify DBRP mapping is configured.

“error connecting InfluxDB influxQL”

Cause: The health check completed but the response couldn’t be processed.

Solution:

Verify the database name is correct.
Check that the user has permission to run SHOW MEASUREMENTS.
Ensure the database exists and contains measurements.
For InfluxDB 2.x, verify DBRP mapping is configured.

SQL health check errors

“error performing sql query”

Cause: The health check query select 1 failed to execute against the FlightSQL endpoint.

Solution:

Verify the InfluxDB URL is correct. The SQL health check connects via gRPC (FlightSQL).
Check the token is valid and has the required permissions.
If using TLS, verify the certificate configuration. Toggle Insecure Connection if connecting without TLS.
Ensure the InfluxDB 3.x instance is running and the FlightSQL endpoint is accessible.

0 measurements found

Error message: datasource is working. 0 measurements found

Cause: The connection is successful, but the database contains no measurements.

Solution:

Verify you are connecting to the correct database.
Check that data has been written to the database.
If the database is new, add some test data to verify the connection.

Query errors

The following errors occur when there are issues with query syntax or execution.

Query syntax error

Error message: “error parsing query: found THING” or “failed to parse query: found WERE, expected ; at line 1, char 38”

Cause: The query contains invalid syntax.

Solution:

Check your query syntax for typos or invalid keywords.
For InfluxQL, verify the query follows the correct syntax:
SQL
```
SELECT <field> FROM <measurement> WHERE <condition>
```
For SQL, verify your query uses standard SQL syntax supported by InfluxDB 3.x. Common issues include using InfluxQL-specific syntax (such as GROUP BY time()) in SQL mode. Refer to the InfluxDB SQL reference for supported functions.
For Flux, ensure proper pipe-forward syntax and function calls.
Use the InfluxDB UI or CLI to test your query directly.

Query timeout limit exceeded

Error message: “query-timeout limit exceeded”

Cause: The query took longer than the configured timeout limit in InfluxDB.

Solution:

Reduce the time range of your query.
Add more specific filters to limit the data scanned.
Increase the query timeout setting in InfluxDB if you have administrator access.
Optimize your query to reduce complexity.

Too many series or data points

Error message: “max-series-per-database limit exceeded” or “A query returned too many data points and the results have been truncated”

Cause: The query is returning more data than the configured limits allow.

Solution:

Reduce the time range of your query.
Add filters to limit the number of series returned.
Increase the Max series setting in the data source configuration under Advanced Database Settings.
Use aggregation functions to reduce the number of data points.
For SQL, use $__dateBin(time) to aggregate data into time buckets and reduce cardinality.
For Flux, use aggregateWindow() to downsample data.

FlightSQL errors (SQL query language)

Error message: Messages prefixed with "flightsql: " followed by a gRPC error description.

Cause: The SQL (FlightSQL) backend encountered an error communicating with InfluxDB 3.x.

Possible causes and solutions:

Error code	Cause	Solution
`InvalidArgument`	The SQL query syntax is invalid.	Check your SQL query for syntax errors.
`PermissionDenied`	The token doesn’t have access to the requested resource.	Verify the token has read access to the database.
`NotFound`	The requested table or database doesn’t exist.	Check the database name and table name in your query.
`Unavailable`	The InfluxDB server is unreachable.	Verify InfluxDB is running and the URL is correct.
`Unauthenticated`	The token is missing, invalid, or expired.	Update the token in the data source configuration.

No time column found

Error message: “no time column found”

Cause: The query result doesn’t include a time column, which is required for time-series visualization.

Solution:

Ensure your query includes a time field.
For Flux, verify the query includes _time in the output.
For SQL, ensure the query returns a timestamp column.
Check that the time field is not being filtered out or excluded.

Annotation errors

The following errors occur when using InfluxDB annotations on dashboards.

“Query missing in annotation definition”

Cause: The annotation query field is empty.

Solution:

Navigate to the dashboard you want to update and click Edit.
Click the Dashboard options icon to open the sidebar.
Expand the Annotations section.
Select the InfluxDB annotation.
Click Open query editor to open the Annotation Query dialog box.
Enter a valid query in the InfluxQL Query field. The query must include WHERE $timeFilter. For example:
SQL
```
SELECT title, description FROM events WHERE $timeFilter ORDER BY time ASC
```

“Flux requires the standard annotation query”

Cause: A Flux data source is using the legacy InfluxQL annotation editor instead of the standard Flux query editor.

Solution:

Delete the existing annotation query.
Create a new annotation query and select your Flux-configured InfluxDB data source.

Write a Flux query that returns data frames with time and text fields. For example:

from(bucket: "events")
  |> range(start: v.timeRangeStart, stop: v.timeRangeStop)
  |> filter(fn: (r) => r["_measurement"] == "deployments")

Annotations don’t appear on the graph

Cause: Annotations are configured but aren’t visible on the dashboard.

Solution:

Verify the annotation query returns data by testing it in Explore.
Check the dashboard time range covers the time period of your annotation events.
Ensure the annotation toggle is enabled in the dashboard (check the annotation icon in the top menu bar).
For InfluxQL, confirm the query includes WHERE $timeFilter.
If your query returns multiple columns, verify the field mappings (Text, Tags, TimeEnd) are set correctly.

Alerting errors

The following errors occur when using InfluxDB queries with Grafana Alerting.

Alert rule fails with template variable errors

Cause: The alert query contains template variables such as $hostname or $region.

Solution:

Alert queries can’t use template variables because Grafana evaluates alert rules on the backend without dashboard context. Replace template variables with hard-coded values:

Open the alert rule.
Replace any $variable references with literal values.
Save the alert rule.

If you need the same query in both a dashboard panel and an alert rule, maintain two separate queries: one with variables for the dashboard and one with hard-coded values for alerting.

Alert evaluation returns “no data”

Cause: The alert query doesn’t return time-series data that Grafana can evaluate.

Solution:

Test the query in Explore first to verify it returns data.
For InfluxQL, ensure the query uses an aggregation function (such as mean, sum, count) with GROUP BY time($__interval).
For Flux, use aggregateWindow() to produce time-bucketed results.
For SQL, use $__dateBin(time) or $__timeGroup(time) to aggregate by time.
Check that the alert evaluation time range contains data. Alerts use a fixed time range, not the dashboard’s time picker.
Verify the data source connection is working by clicking Save & test in the data source settings.

Template variable errors

The following issues occur when using template variables with InfluxDB queries.

Variable drop-down shows stale or historical values

Cause: Metadata queries such as SHOW TAG VALUES return values from the entire retention period, not just the dashboard time range. Hosts or sensors that stopped reporting long ago still appear in the drop-down.

Solution:

Add a time condition to the variable query, such as WHERE $timeFilter for InfluxQL or WHERE $__timeFilter(time) for SQL.
Set the variable’s Refresh option to On time range change.
Refer to Scope variables to the dashboard time range for examples.

Multi-select variable breaks the query

Cause: When a variable has the Multi-value or Include all value option enabled, Grafana interpolates the selected values as a regular expression group, such as (server1|server2). Queries that compare with = or that don’t wrap the variable in a regular expression fail or return no data.

Solution:

For InfluxQL, use the =~ operator and wrap the variable in a regular expression: "hostname" =~ /^$host$/.
For SQL, use the IN operator: host IN ($host).
Refer to Choose a variable syntax for working examples.

Variable values are escaped unexpectedly

Cause: Grafana escapes special characters in variable values when the variable is multi-value or used inside a regular expression. Custom variable values that intentionally contain special characters, such as paths or expressions, arrive at InfluxDB modified.

Solution:

Use the raw format option, such as ${path:raw}, to interpolate the literal value without escaping. Refer to Prevent unwanted value escaping for details.

Variable drop-down contains a blank or duplicate entry

Cause: The variable query returns duplicate values. Grafana deduplicates results, but depending on the plugin version, duplicates can surface as a blank entry in the drop-down.

Solution:

Update the variable query to return unique values. For SQL, use SELECT DISTINCT. For InfluxQL, SHOW metadata queries already return unique values, so check for duplicates across retention policies.
Alternatively, use the variable’s Regex option to filter the results.

Other common issues

The following issues don’t produce specific error messages but are commonly encountered during day-to-day use.

“Data source was not found”

Symptoms:

Dashboard panels display “data source <UID> was not found”
Manually re-running queries in the panel editor works after you select the data source again

Cause: Dashboard panels reference an old or deleted data source UID. This happens when a data source is deleted and recreated, since the new data source gets a different UID. Dashboard schema migrations can also leave panels with invalid data source references, so verify your panels after a dashboard is migrated to a new schema version.

Solution:

Find the current UID of your InfluxDB data source. Navigate to Connections > Data sources, open the data source, and copy the UID from the page URL.
To find every stale reference at once, open the dashboard’s JSON model from the dashboard settings and search for the UID shown in the panel error message.
Fix the references by editing each affected panel and selecting the correct InfluxDB data source from the drop-down again, or by replacing the stale UID in the JSON model and saving the dashboard.
To avoid this issue, update existing data sources instead of deleting and recreating them.

404 Not Found when sending Telegraf metrics to Grafana Cloud

Error message: “404 Not Found” when Telegraf writes to the Grafana Cloud InfluxDB-compatible endpoint.

Cause: The Telegraf influxdb_v2 output plugin isn’t compatible with the Grafana Cloud metrics endpoint. This commonly occurs when using PrivateLink or the standard InfluxDB-compatible write endpoint.

Solution:

Switch the Telegraf output plugin from influxdb_v2 to influxdb (v1) in your Telegraf configuration.
Ensure the endpoint URL and credentials match those shown in your Grafana Cloud InfluxDB configuration page.
Restart Telegraf after making the change.

Empty query results

Cause: The query returns no data.

Solution:

Verify the time range includes data in your database.
Check that the measurement and field names are correct. For SQL, table names in InfluxDB 3.x are case-sensitive.
Test the query directly in the InfluxDB UI or CLI.
Ensure filters are not excluding all data.
For SQL, verify the $__timeFilter(time) macro is included so the query uses the dashboard time range.
For InfluxQL, verify the retention policy contains data for the selected time range.

Numeric values stored as strings display a blank panel

Symptoms:

Time series panels show no data even though the query returns results
Values appear in the table view but can’t be graphed

Cause: InfluxDB sets a field’s data type when the field is first written. If numeric values were written as strings, for example quoted in line protocol, InfluxDB returns them as strings and Grafana can’t graph them. This is a data issue in InfluxDB, not in Grafana.

Solution:

As a workaround, add the Convert field type transformation to the panel and convert the field to Number.
To fix the root cause, correct the data type at write time. InfluxDB can’t change the type of an existing field, so you may need to write the data to a new field or measurement.
In older Grafana versions, the Convert field type transformation converted null values to zeros. Current versions preserve null values. If you see nulls displayed as zeros after conversion, upgrade Grafana.

Panel values differ between view and edit mode

Cause: Grafana calculates the query interval ($__interval) from the time range and the maximum number of data points, which is based on the panel’s width. A panel rendered in edit mode has a different width than in the dashboard view, so queries that group by time($__interval) can aggregate into different bucket sizes and display different values. Both results are correct. They’re aggregated at different resolutions.

Solution:

To make values consistent, set a fixed Min interval or Max data points value in the panel’s query options.
Alternatively, use an explicit interval in the query, such as GROUP BY time(1m) instead of GROUP BY time($__interval).

Cause: The query returns multiple series with the same name. This commonly happens when a query doesn’t group by the tags that differentiate series, or when an alias hides the distinguishing information. Grafana assigns colors and tooltip values by series name, so duplicate names cause the legend and hover tooltip to display mismatched colors or values.

Solution:

Group by the tags that make each series unique, such as GROUP BY "hostname".
Use alias patterns such as $tag_hostname in the ALIAS field so each series has a unique display name. Refer to Alias patterns for details.
Use the panel inspector to confirm each returned series has a distinct name.

Slow query performance

Cause: Queries take a long time to execute.

Solution:

Reduce the time range of your query.
Add more specific filters to limit the data scanned.
Increase the Min time interval setting to reduce the number of data points.
Check InfluxDB server performance and resource utilization.
For SQL, use $__dateBin(time) with aggregation functions to downsample data. Add WHERE clauses to narrow the query scope.
For Flux, use aggregateWindow() to downsample data before visualization.
Consider using continuous queries or tasks to pre-aggregate data.

InfluxDB receives a high volume of queries from Grafana

Symptoms:

Unexpected query load on your InfluxDB server
You’re unsure whether the traffic originates from Grafana

Cause: Every panel on a dashboard sends its queries to InfluxDB each time the dashboard refreshes. Query volume scales with the number of panels, the number of queries per panel, the refresh interval, and the number of people viewing the dashboard at the same time. For example, a dashboard with 20 panels refreshing every 10 seconds generates at least 120 queries per minute for each viewer.

Solution:

Increase the dashboard refresh interval or turn off auto-refresh where it isn’t needed.
Reduce the number of panels and queries per dashboard.
Increase the Min time interval setting to reduce the resolution of each query.
In Grafana Enterprise and Grafana Cloud, enable query caching so identical queries within the cache window are served from cache instead of hitting InfluxDB.
To confirm whether traffic originates from your Grafana Cloud instance, compare the source IP addresses against the Grafana Cloud allowlist.

Data appears delayed or missing recent points

Cause: The visualization doesn’t show the most recent data.

Solution:

Check the dashboard time range and refresh settings.
Verify the Min time interval is not set too high.
Ensure InfluxDB has finished writing the data.
Check for clock synchronization issues between Grafana and InfluxDB.

Enable debug logging

Caution
InfluxDB plugin versions earlier than 13.1.0 could write API tokens to Grafana server logs in plain text at default log levels. Before troubleshooting with logs, upgrade to plugin version 13.1.0 or later. Treat log files as sensitive, and rotate any tokens that may have been exposed.

To capture detailed error information for troubleshooting:

Set the Grafana log level to debug in the configuration file:
ini
```
[log]
level = debug
```
Review logs in /var/log/grafana/grafana.log (or your configured log location).
Look for InfluxDB-specific entries that include request and response details.
Reset the log level to info after troubleshooting to avoid excessive log volume.

Get additional help

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

Check the InfluxDB documentation for API-specific guidance.
Review the Grafana community forums for similar issues.
Review InfluxDB data source issues on GitHub for known bugs.
Contact Grafana Support if you’re an Enterprise, Cloud Pro, or Cloud Contracted user.
When reporting issues, include:
- Grafana version
- InfluxDB data source plugin version, found on the Administration > Plugins page
- InfluxDB version and product (OSS, Cloud, Enterprise)
- Query language (Flux, InfluxQL, or SQL)
- Error messages (redact sensitive information)
- Steps to reproduce
- Relevant configuration such as data source settings, HTTP method, and TLS settings (redact tokens, passwords, and other credentials)