docs/sources/datasources/mssql/troubleshooting/index.md
This document provides solutions to common issues you may encounter when configuring or using the Microsoft SQL Server (MSSQL) data source in Grafana.
These errors occur when setting up or accessing the data source configuration in Grafana.
Symptoms: The data source settings page shows only Delete and Back buttons with no configuration fields.
Cause: The logged-in user has insufficient permissions to configure data sources. Only users with the Organization administrator role (or a custom RBAC role with datasources:write permissions) can access the data source configuration form.
Solution:
Organization administrator role, or assign you a custom RBAC role with data source write permissions.These errors occur when Grafana cannot establish or maintain a connection to the Microsoft SQL Server.
Error message: Unable to open tcp connection or dial tcp: connection refused
Cause: Grafana cannot establish a network connection to the SQL Server.
Solution:
1433.Error message: "Connection timed out" or "I/O timeout"
Cause: The connection to SQL Server timed out before receiving a response.
Solution:
Error message: "TLS handshake failed" or "certificate verify failed"
Cause: There is a mismatch between the encryption settings in Grafana and what the SQL Server supports or requires.
Solution:
Error message: "TLS handshake failed" or "no cipher suite supported by both client and server"
Cause: Grafana builds using BoringCrypto (FIPS-compliant builds) enforce FIPS 140-3 cipher requirements. SQL Server instances that only support older cipher suites (TLS 1.0, RC4, or 3DES) are incompatible with these builds.
Solution:
Error message: "certificate verify failed" or "x509: certificate signed by unknown authority" when connecting through Private data source connect
Cause: The SQL Server's TLS certificate must be verifiable from the PDC agent's perspective, not from Grafana Cloud. If the SQL Server uses a private CA certificate, the PDC agent host must trust that CA.
Solution:
openssl s_client -connect <SQL_SERVER_HOST>:1433 -starttls mssql.Error message: "Cannot connect to named instance" or connection fails when using instance name
Cause: Grafana cannot resolve the SQL Server named instance.
Solution:
hostname\instancename or hostname\instancename,port in the Host field.hostname,port.These errors occur when using Grafana Cloud with Private data source connect to reach an on-premises or private-network SQL Server.
Error message: dial tcp: lookup sqlserver.internal.example.com: no such host
Cause: The PDC agent cannot resolve the SQL Server hostname from its network. This commonly occurs when:
Solution:
nslookup <SQL_SERVER_HOST> from the agent machine.Cause: The PDC SSH tunnel endpoint IP changed after infrastructure maintenance, breaking the established connection.
Solution:
Cause: A known issue can cause the data source username to not persist when PDC is enabled.
Solution:
Cause: Attempting to connect to an on-premises or private-network SQL Server from Grafana Cloud without PDC configured.
Solution:
For setup instructions, refer to Connect to on-premises SQL Server from Grafana Cloud.
These errors occur when there are issues with authentication credentials or permissions.
Error message: "Login failed for user 'username'" or "Authentication failed"
Cause: The authentication credentials are invalid or the user doesn't have permission to access the database.
Solution:
DOMAIN\User).Error message: "Login failed for user ''"—the saved username appears blank when Grafana connects to SQL Server.
Cause: A known issue on certain Grafana release channels caused the SQL Server Authentication username to appear saved in the UI but send an empty string to the server during connection. This was identified on the "fast" release channel.
Solution:
Error message: "Login failed for user" or "Connection string parse error" when credentials contain semicolons (;) or closing braces (})
Cause: In Grafana versions prior to v13.0, semicolons and closing braces in usernames or passwords were not properly escaped in the MSSQL connection string, causing authentication failures.
Solution:
; and } characters.Error message: Cannot open database 'dbname' requested by the login
Cause: The authenticated user doesn't have permission to access the specified database.
Solution:
Verify that the database name is correct in the data source configuration.
Ensure the user is mapped to the database with appropriate permissions.
Grant at least SELECT permission on the required tables:
USE [your_database]
GRANT SELECT ON dbo.YourTable TO [your_user]
Check that the user doesn't have any conflicting permissions from the public role.
Error message: "Kerberos authentication failed" or "Cannot initialize Kerberos"
Cause: Kerberos configuration is incorrect or incomplete.
Solution:
krb5.conf) path is correct in the data source settings. The default path is /etc/krb5.conf.{{< admonition type="note" >}} Kerberos authentication is not supported in Grafana Cloud. Use SQL Server Authentication or Azure Entra ID instead. {{< /admonition >}}
Error message: "KDC_ERR_C_PRINCIPAL_UNKNOWN" when connecting through a SQL Server Availability Group Listener
Cause: The SPN registered for the SQL Server instance doesn't match the Availability Group Listener's DNS name. Kerberos authentication requires an SPN that matches the hostname the client connects to.
Solution:
Register an SPN for the Availability Group Listener DNS name:
setspn -S MSSQLSvc/<LISTENER_FQDN>:1433 <DOMAIN>\<SERVICE_ACCOUNT>
setspn -S MSSQLSvc/<LISTENER_FQDN> <DOMAIN>\<SERVICE_ACCOUNT>
Verify the SPN is correctly registered: setspn -L <DOMAIN>\<SERVICE_ACCOUNT>.
Ensure krb5.conf includes the correct realm mapping for the listener's domain.
If using multiple realms, add cross-realm trust entries to krb5.conf.
Error message: "The login is from an untrusted domain and cannot be used with Windows authentication"
Cause: The Grafana server's domain isn't trusted by the SQL Server's domain, or the Kerberos realm configuration doesn't map correctly between domains.
Solution:
Verify that a trust relationship exists between the Grafana server's domain and the SQL Server's domain.
Check that krb5.conf includes realm mappings for both domains:
[realms]
DOMAIN_A.COM = {
kdc = kdc1.domain_a.com
}
DOMAIN_B.COM = {
kdc = kdc1.domain_b.com
}
[domain_realm]
.domain_a.com = DOMAIN_A.COM
.domain_b.com = DOMAIN_B.COM
Ensure the SQL Server service account has delegation permissions if cross-domain access is needed.
As an alternative, use SQL Server Authentication or Azure Entra ID (App Registration), which don't require domain trust.
Error message: "AADSTS error codes" or "Azure AD authentication failed"
Cause: Azure Entra ID (formerly Azure AD) authentication is misconfigured.
Solution:
For App Registration authentication:
For Managed Identity authentication:
managed_identity_enabled = true is set in the Grafana server configuration.For Current User authentication:
user_identity_enabled = true is set in the Grafana server configuration.user_impersonation for Azure SQL).For detailed Azure authentication configuration, refer to Configure the Microsoft SQL Server data source.
These errors occur when there are issues with query syntax or configuration.
Error message: "Could not find time column" or time series visualization shows no data
Cause: The query doesn't return a properly formatted time column for time series visualization.
Solution:
time when using the Time series format.$__time() macro to rename your date column: $__time(your_date_column).datetime, datetime2, date) or contains Unix epoch values.ORDER BY.Error message: "Error parsing query" or macros appear unexpanded in the query
Cause: Grafana macros are being used incorrectly.
Solution:
$__timeFilter(column) not $_timeFilter(column).Cause: Time series data appears shifted or doesn't align with expected times.
Solution:
Store timestamps in UTC in your database to avoid timezone issues.
Time macros ($__time, $__timeFilter, etc.) always expand to UTC values.
If your timestamps are stored in local time, convert them to UTC in your query:
SELECT
your_datetime_column AT TIME ZONE 'Your Local Timezone' AT TIME ZONE 'UTC' AS time,
value
FROM your_table
Don't pass timezone parameters to time macros—they're not supported.
Error message: "Result set too large" or browser becomes unresponsive
Cause: The query returns more data than can be efficiently processed.
Solution:
$__timeFilter(column) to limit data to the dashboard time range.AVG, SUM, COUNT) with GROUP BY instead of returning raw rows.TOP clause to limit results: SELECT TOP 1000 ....$__timeGroup() macro to aggregate data into time intervals.Cause: Stored procedure output isn't being captured correctly.
Solution:
SELECT statements, not just variable assignments.SET NOCOUNT ON if present, or ensure it's followed by a SELECT statement.For more information on using stored procedures, refer to the query editor documentation.
These issues relate to slow queries or high resource usage.
Cause: Queries take a long time to execute.
Solution:
WHERE clauses and time filters.Error message: "Too many connections", "Connection pool exhausted", or "failed to connect to server"
Cause: Too many concurrent connections to the database. This commonly manifests as intermittent alert failures while dashboards continue to work, because alert evaluations and dashboard queries compete for connections from the same pool.
Solution:
50 to 100 handles most deployments with concurrent dashboards and alerts.14400 (4 hours) to ensure stale connections are recycled.sys.dm_exec_sessions).Symptoms: Dashboards take 5 to 6 minutes to load initially, or queries are significantly slower than expected.
Cause: The data source is configured with ApplicationIntent=ReadOnly in the Host field, which routes all queries to a read-only secondary replica. If the replica is undersized, under-indexed, or experiencing replication lag, queries run much slower than on the primary.
Solution:
ApplicationIntent=ReadOnly from the Host field to route queries back to the primary instance.These errors occur when using Microsoft SQL Server queries in Grafana Alerting.
Cause: Connection pool exhaustion. Alert evaluations and dashboard queries share the same connection pool. Under concurrent load, alert evaluations may time out waiting for a free connection.
Solution:
Refer to Connection pool exhaustion in the Performance issues section above.
Cause: Alert queries have different requirements than dashboard queries.
Solution:
For more information, refer to Microsoft SQL Server alerting.
These errors occur when using template variables in queries.
Cause: Variable queries return unexpected results or errors.
Solution:
Cause: Since Grafana v11.3, multi-value variables used with IN are automatically quoted. If you manually wrapped the variable in quotes (for example, WHERE col IN ('${var}')), values are now double-quoted (for example, ''value''), causing query failures.
Solution:
WHERE col IN ($var) instead of WHERE col IN ('${var}').sqlstring format: WHERE col = ${var:sqlstring}.The following issues don't produce specific error messages but are commonly encountered.
Cause: Queries accidentally access system databases.
Solution:
tempdb, model, msdb, and master from the database dropdown.Cause: Data formatting or type conversion issues.
Solution:
SELECT value AS metric.NULL values that might affect aggregations.FILL option in $__timeGroup() macro to handle missing data points.If you continue to experience issues after following this troubleshooting guide:
When reporting issues, include: