InfluxDB data source on Grafana Labs

Configure the InfluxDB data source

Fri, 03 Apr 2026 19:43:06 +0000

Configure the InfluxDB data source

Learn how to configure the InfluxDB data source and explore the available configuration options.

Before you begin

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

InfluxData provides three query languages:

Flux - A functional data scripting language for InfluxDB 2.x. Refer to Query InfluxDB with Flux for a basic guide on working with Flux.
InfluxQL - A SQL-like query language developed by InfluxData. It doesn’t support advanced functions such as JOINs.
SQL - Native SQL language available for InfluxDB v3.x.

To help choose the best language for your needs, refer to a comparison of Flux vs InfluxQL and Why InfluxData created Flux.

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.

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 - Set an HTTP request timeout in seconds.

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 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’s autocomplete to reduce the execution time of tag filter queries. As a result, any tags not present within the defined time range will be filtered out. For example, setting the value to 12h will include only tag keys/values from the past 12 hours. This feature is recommended for use with 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.

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

Fri, 03 Apr 2026 19:43:06 +0000

InfluxDB query editor

Grafana’s query editors are unique to each data source. For general information on Grafana query editors, refer to Query editors. For general information on querying data sources in Grafana, refer to Query and transform data.

The InfluxDB query editor is located on the Explore page. You can also access the InfluxDB query editor from a dashboard panel. Click the ellipsis in the upper right of the panel and select Edit.

You can also use the query editor to retrieve log data and annotate visualizations.

Choose a query editing mode

The InfluxDB data source has three different types of 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.
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 on this option.
FORMAT AS - Select a format option from the drop-down menu.
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. Note that when you switch to visual editor mode, you will lose any changes made in raw query mode.

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 regex pattern in forward slashes (/), as shown in this example: /measurement/.

Grafana automatically adjusts the filter tag condition to use the InfluxDB regex 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.

If you have the following:

The query editor input generates an InfluxDB SELECT clause:

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 `$tagyourTagName` 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 in InfluxDB v3.0 and higher.

You construct your SQL query directly in the query editor.

Macros

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

Macro example	Replaced with
`$__timeFrom`	The start of the currently active time selection, such as `2020-06-11T13:31:00Z`.
`$__timeTo`	The end of the currently active time selection, such as `2020-06-11T14:31:00Z`.
`$__timeFilter`	The time range that applies the start and the end of currently active time selection.
`$__interval`	An interval string that corresponds to Grafana’s calculated interval based on the time range of the active time selection, such as `5s`.
`$__dateBin(<column>)`	Applies date_bin function. Column must be timestamp.
`$__dateBinAlias(<column>)`	Applies date_bin function with suffix `_binned`. Column must be timestamp.

Examples:

// with macro
1. SELECT * FROM cpu WHERE time >= $__timeFrom AND time <= $__timeTo
2. SELECT * FROM cpu WHERE $__timeFilter(time)
3. SELECT $__dateBin(time) from cpu

// interpolated
1. SELECT * FROM iox.cpu WHERE time >= cast('2023-12-15T12:38:30Z' as timestamp) AND time <= cast('2023-12-15T18:38:30Z' as timestamp)
2. SELECT * FROM cpu WHERE time >= '2023-12-15T12:41:28Z' AND time <= '2023-12-15T18:41:28Z'
3. SELECT date_bin(interval '15 second', time, timestamp '1970-01-01T00:00:00Z') from cpu

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 Grafana’s context. Macros support copying and pasting from 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 Grafana’s calculated interval based on the time range of the active time selection, such as `5s`.
`v.defaultBucket`	The data source configuration’s “Default Bucket” setting.
`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")

This Flux query is interpolated into the following query and sent 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.

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 will display the log message. Add any additional filters by clicking the + sign next to the WHERE field. Add additional conditions in the GROUP BY, ORDER BY and the rest of the options.

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.

Apply annotations

Annotations overlay rich event information on top of graphs. You can add annotation queries in the dashboard menu’s Annotations view.

For InfluxDB, your query must include WHERE $timeFilter.

If you select only one column, you don’t need to enter anything in the column mapping fields.

The Tags field’s value can be a comma-separated string.

Annotation query example

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

InfluxDB template variables

Fri, 03 Apr 2026 19:43:06 +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 additional information using variables and templates, refer to the following documentation:

Use query variables

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.

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

SHOW TAG VALUES WITH KEY = "hostname"

Chain or nest variables

You can also 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 using the following query:

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

You can also fetch key names for a given measurement:

SHOW TAG KEYS [FROM <measurement_name>]

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 ad hoc filters

InfluxDB supports the Ad hoc filters variable type. This variable type allows you to define multiple key/value filters, which Grafana then automatically applies to all your InfluxDB queries.

For more information, refer to Add ad hoc filters.

Choose a variable syntax

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

$<varname> - This syntax is easy to read and write but does not allow you to use a variable in the middle of a word or expression.
SQL
```
SELECT mean("value") FROM "logins" WHERE "hostname" =~ /^$host$/ AND $timeFilter GROUP BY time($__interval), "hostname"
```

${varname} - Use this syntax when you want to interpolate a variable in the middle of an expression.

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, Grafana converts the labels from plain text to a regex-compatible string, so you must use =~ instead of =.

Templated dashboard example

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

Troubleshoot InfluxDB data source issues

Fri, 03 Apr 2026 19:43:06 +0000

Troubleshoot InfluxDB data source issues

This document provides troubleshooting guidance for common errors you may encounter when using the InfluxDB data source in Grafana.

Connection errors

The following errors occur when Grafana cannot establish or maintain a connection to InfluxDB.

Failed to connect to InfluxDB

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

Cause: Grafana cannot 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.

Request timed out

Error message: “context deadline exceeded” or “request timeout”

Cause: The connection to InfluxDB timed out before receiving a response.

Solution:

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.

Solution:

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 does not 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.

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.
Ensure the selected query language matches your InfluxDB version:
- Flux: InfluxDB 1.8+ and 2.x
- InfluxQL: InfluxDB 1.x and 2.x (with DBRP mapping)
- SQL: InfluxDB 3.x only

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.

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 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 admin 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 Flux, use aggregateWindow() to downsample data.

No time column found

Error message: “no time column found”

Cause: The query result does not 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.

Health check errors

The following errors occur when testing the data source connection.

Error getting flux query buckets

Error message: “error getting flux query buckets”

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

Solution:

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

Error connecting InfluxDB influxQL

Error message: “error connecting InfluxDB influxQL”

Cause: The health check query SHOW MEASUREMENTS failed.

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.

0 measurements found

Error message: “data source 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.

Other common issues

The following issues don’t produce specific error messages but are commonly encountered.

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.
Test the query directly in the InfluxDB UI or CLI.
Ensure filters are not excluding all data.
For InfluxQL, verify the retention policy contains data for the selected time range.

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 Flux, use aggregateWindow() to downsample data before visualization.
Consider using continuous queries or tasks to pre-aggregate data.

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.

Get additional help

If you continue to experience issues after following this troubleshooting guide:

Check the InfluxDB documentation for API-specific guidance.
Review the Grafana community forums for similar issues.
Contact Grafana Support if you’re an Enterprise, Cloud Pro or Cloud Contracted user.
When reporting issues, include:
- Grafana version
- 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)