Troubleshoot PostgreSQL data source issues

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

Connection errors

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

Failed to connect to PostgreSQL

Error message: failed to connect to ... : connect: connection refused or dial tcp: connect: connection refused

Cause: Grafana cannot establish a network connection to the PostgreSQL server.

Solution:

Verify that the Host URL is correct in the data source configuration.
Check that PostgreSQL is running and accessible from the Grafana server.
Verify the port is correct (the PostgreSQL default port is 5432).
Ensure there are no firewall rules blocking the connection.
Check that PostgreSQL is configured to accept connections from the Grafana server in pg_hba.conf.
For Grafana Cloud, ensure you have configured Private data source connect if your PostgreSQL instance is not publicly accessible.

Request timed out

Error message: "context deadline exceeded" or "i/o timeout"

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

Solution:

Check the network latency between Grafana and PostgreSQL.
Verify that PostgreSQL is not overloaded or experiencing performance issues.
Increase the Max lifetime setting in the data source configuration under Connection limits.
Reduce the time range or complexity of your query.
Check if any network devices (load balancers, proxies) are timing out the connection.

Host not found

Error message: failed to connect to ... : hostname resolving error or lookup hostname: no such host

Cause: The hostname specified in the data source configuration cannot be resolved.

Solution:

Verify the hostname is spelled correctly.
Check that DNS resolution is working on the Grafana server.
Try using an IP address instead of a hostname.
Ensure the PostgreSQL server is accessible from the Grafana server's network.

Authentication errors

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

Password authentication failed

Error message: failed to connect to ... : server error: FATAL: password authentication failed for user "username" (SQLSTATE 28P01)

Cause: The username or password is incorrect.

Solution:

Verify that the username and password are correct in the data source configuration.
Check that the user exists in PostgreSQL.
Verify the password has not expired.
If no password is specified, ensure a PostgreSQL password file is configured.

Permission denied

Error message: ERROR: permission denied for table table_name (SQLSTATE 42501) or ERROR: permission denied for schema schema_name (SQLSTATE 42501)

Cause: The database user does not have permission to access the requested table or schema.

Solution:

Verify the user has SELECT permissions on the required tables.

Grant the necessary permissions:

sql

GRANT USAGE ON SCHEMA schema_name TO grafanareader;
GRANT SELECT ON schema_name.table_name TO grafanareader;

Check that the user has access to the correct database.
Verify the search path includes the schema containing your tables.

No pg_hba.conf entry

Error message: failed to connect to ... : server error: FATAL: no pg_hba.conf entry for host "ip_address", user "username", database "database_name" (SQLSTATE 28000)

Cause: PostgreSQL is not configured to accept connections from the Grafana server.

Solution:

Edit the pg_hba.conf file on the PostgreSQL server.
Add an entry to allow connections from the Grafana server:
text
```
host    database_name    username    grafana_ip/32    md5
```
Reload PostgreSQL configuration: SELECT pg_reload_conf();
If using SSL, ensure the correct authentication method is specified (for example, hostssl instead of host).

TLS and certificate errors

The following errors occur when there are issues with TLS configuration.

Certificate verification failed

Error message: "x509: certificate signed by unknown authority" or "certificate verify failed"

Cause: Grafana cannot verify the TLS certificate presented by PostgreSQL.

Solution:

Set the TLS/SSL Mode to the appropriate level (require, verify-ca, or verify-full).
If using a self-signed certificate, add the CA certificate in TLS/SSL Auth Details.
Verify the certificate chain is complete and valid.
Ensure the certificate has not expired.
For testing only, set TLS/SSL Mode to disable (not recommended for production).

SSL not supported

Error message: failed to connect to ... : server refused TLS connection or server does not support SSL

Cause: The PostgreSQL server is not configured for SSL connections, but the data source requires SSL.

Solution:

Set TLS/SSL Mode to disable if SSL is not required.
Alternatively, enable SSL on the PostgreSQL server by configuring ssl = on in postgresql.conf.
Ensure the server has valid SSL certificates configured.

Client certificate error

Error message: "TLS: failed to find any PEM data in certificate input" or "could not load client certificate"

Cause: The client certificate or key is invalid or incorrectly formatted.

Solution:

Verify the certificate and key are in PEM format.
Ensure the certificate file path is correct and readable by the Grafana process.
Check that the certificate and key match (belong to the same key pair).
If using certificate content, ensure you've pasted the complete certificate including headers.

Database errors

The following errors occur when there are issues with the database configuration.

Database does not exist

Error message: failed to connect to ... : server error: FATAL: database "database_name" does not exist (SQLSTATE 3D000)

Cause: The specified database name is incorrect or the database doesn't exist.

Solution:

Verify the database name in the data source configuration.
Check that the database exists: \l in psql or SELECT datname FROM pg_database;
Ensure the database name is case-sensitive and matches exactly.
Verify the user has permission to connect to the database.

Relation does not exist

Error message: ERROR: relation "table_name" does not exist (SQLSTATE 42P01)

Cause: The specified table or view does not exist, or the user cannot access it.

Solution:

Verify the table name is correct and exists in the database.
Check the schema name if the table is not in the public schema.
Use fully qualified names: schema_name.table_name.
Verify the user has SELECT permission on the table.
Check the search path: SHOW search_path;

Query errors

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

Query syntax error

Error message: ERROR: syntax error at or near "keyword" (SQLSTATE 42601)

Cause: The SQL query contains invalid syntax.

Solution:

Check your query syntax for typos or invalid keywords.
Verify column and table names are correctly quoted if they contain special characters or are reserved words.
Use double quotes for identifiers: "column_name".
Test the query directly in a PostgreSQL client (psql, pgAdmin).

Column does not exist

Error message: ERROR: column "column_name" does not exist (SQLSTATE 42703)

Cause: The specified column name is incorrect or doesn't exist in the table.

Solution:

Verify the column name is spelled correctly.
Check that column names are case-sensitive in PostgreSQL when quoted.
Use the correct quoting for column names: "Column_Name" for case-sensitive names.
Verify the column exists in the table: \d table_name in psql.

No time column found

Error message: "no time column found" or time series visualization shows no data

Cause: The query result does not include a properly formatted time column.

Solution:

Ensure your query includes a column named time that returns a timestamp or epoch value.
Use an alias to rename your time column: SELECT created_at AS time.
Ensure the time column is of type timestamp, timestamptz, or a numeric epoch value.
Order results by the time column: ORDER BY time ASC.

Macro expansion error

Error message: "macro '$__timeFilter' not found" or incorrect query results with macros

Cause: Grafana macros are not being properly expanded.

Solution:

Verify the macro syntax is correct, for example $__timeFilter(time_column).
Ensure the column name passed to the macro exists in your table.
Use the Preview toggle in Builder mode to see the expanded query.
For time-based macros, ensure the column contains timestamp data.

Performance issues

The following issues relate to slow query execution or resource constraints.

Query timeout

Error message: "canceling statement due to statement timeout" or "query timeout"

Cause: The query took longer than the configured timeout.

Solution:

Reduce the time range of your query.
Add indexes to columns used in WHERE clauses and joins.
Use the $__timeFilter macro to limit data to the dashboard time range.
Increase the statement timeout in PostgreSQL if you have admin access.
Optimize your query to reduce complexity.

Too many connections

Error message: failed to connect to ... : server error: FATAL: too many connections for role "username" (SQLSTATE 53300) or connection pool exhausted

Cause: The maximum number of connections to PostgreSQL has been reached.

Solution:

Reduce the Max open connections setting in the data source configuration.
Increase max_connections in PostgreSQL's postgresql.conf if you have admin access.
Check for connection leaks in other applications connecting to the same database.
Enable Auto max idle to automatically manage idle connections.

Slow query performance

Cause: Queries take a long time to execute.

Solution:

Reduce the time range of your query.
Add appropriate indexes to your tables.
Use the $__timeFilter macro to limit the data scanned.
Increase the Min time interval setting to reduce the number of data points.
Use EXPLAIN ANALYZE in PostgreSQL to identify query bottlenecks.
Consider using materialized views for complex aggregations.

Provisioning errors

The following errors occur when provisioning the data source via YAML.

Invalid provisioning configuration

Error message: "metric request error" or data source test fails after provisioning

Cause: The provisioning YAML file contains incorrect configuration.

Solution:

Ensure parameter names match the expected format exactly.
Verify the database name is not included in the URL.
Use the correct format for the URL: hostname:port.
Check that string values are properly quoted in the YAML file.
Refer to the provisioning example for the correct format.

Example correct configuration:

yaml

datasources:
  - name: Postgres
    type: postgres
    url: localhost:5432
    user: grafana
    secureJsonData:
      password: 'Password!'
    jsonData:
      database: grafana
      sslmode: 'disable'

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 table and column names are correct.
Test the query directly in PostgreSQL.
Ensure filters are not excluding all data.
Verify the $__timeFilter macro is using the correct time column.

TimescaleDB functions not available

Cause: TimescaleDB-specific functions like time_bucket are not available in the query builder.

Solution:

Enable the TimescaleDB toggle in the data source configuration under PostgreSQL Options.
Verify TimescaleDB is installed and enabled in your PostgreSQL database.
Check that the timescaledb extension is created: CREATE EXTENSION IF NOT EXISTS timescaledb;

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 data has been committed to the database (not in an uncommitted transaction).
Check for clock synchronization issues between Grafana and PostgreSQL.

Get additional help

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

Check the PostgreSQL documentation for database-specific guidance.
Review the Grafana community forums for similar issues.
Contact Grafana Support if you are a Cloud Pro, Cloud Contracted, or Enterprise user.
When reporting issues, include:
- Grafana version
- PostgreSQL version
- Error messages (redact sensitive information)
- Steps to reproduce
- Relevant configuration such as data source settings, TLS mode, and connection limits (redact passwords and other credentials)