Troubleshooting

Grafana Cloud Enterprise

Troubleshoot IBM Db2 data source issues

This document provides solutions to common issues you might encounter when configuring or using the IBM Db2 data source. For configuration instructions, refer to Configure the IBM Db2 data source.

Connection errors

These errors occur when Grafana cannot connect to the IBM Db2 database.

“Database instance not reachable”

Symptoms:

Save & test fails with “Database instance not reachable”
Queries fail with connection errors

Possible causes and solutions:

Cause	Solution
Database server is not running	Start the IBM Db2 database server.
Incorrect host or port	Verify the Host URL in the data source configuration matches your Db2 server.
Firewall blocking connection	Ensure your firewall allows outbound connections to the Db2 server port (typically 50000).
Network connectivity issue	Test connectivity from the Grafana server to the Db2 host using `nc -zv <host> <port>`.

“DB2 instance not reachable”

Symptoms:

Save & test fails with “DB2 instance not reachable”
Error messages containing SQL30081N or SQLSTATE=08001

Solutions:

Verify the Db2 server is running and accepting connections.
Check that the database manager is started on the Db2 server.
Confirm the port number is correct (default is 50000).
Test connectivity: nc -zv <host> 50000

“Missing resource bundle” (ERRORCODE=-4222)

Symptoms:

Error message: [jcc]Missing resource bundle: A resource bundle could not be found in the com.ibm.db2.jcc package ERRORCODE=-4222, SQLSTATE=08001

Solutions:

This error typically indicates a connectivity issue, not a missing driver.

Verify the Db2 server is running.
Test network connectivity to the Db2 host and port.
Check that the database manager is initialized and accepting connections.
If using Docker, verify the container is running: docker ps | grep db2

“Connection timeout”

Symptoms:

Save & test times out
Error message mentions “timeout” or “timed out”

Possible causes and solutions:

Cause	Solution
Database server is overloaded	Check database server performance and resources.
Network latency	Verify network connectivity between Grafana and the Db2 server.
Firewall silently dropping packets	Check firewall rules; ensure the Db2 port is open.

“Cannot resolve database hostname”

Symptoms:

Error message mentions “unknown host” or “name resolution”

Solutions:

Verify the hostname is spelled correctly in the Host URL.
Check DNS resolution from the Grafana server: nslookup <hostname>
If using an IP address, ensure it’s correct and reachable.
For internal hostnames, verify the Grafana server can resolve them.

Authentication errors

These errors occur when credentials are invalid or the user lacks required permissions.

“Authentication failed” or “Access denied”

Symptoms:

Save & test fails with authentication errors
Error messages mention “authentication”, “access denied”, or “login failed”

Possible causes and solutions:

Cause	Solution
Incorrect username	Verify the username in the data source configuration.
Incorrect password	Re-enter the password; it may have been changed.
Account locked	Check if the database account is locked or expired.
Insufficient permissions	Ensure the user has CONNECT privilege on the database.

Query errors

These errors occur when executing queries against the database.

Empty results or “No data”

Symptoms:

Query executes without error but returns no data
Panels show “No data” message

Possible causes and solutions:

Cause	Solution
Query returns no matching rows	Verify your WHERE clause and expand the dashboard time range.
Wrong database selected	Check that you’re querying the correct database.
Table or column doesn’t exist	Verify table and column names in your query.
Case sensitivity	Db2 object names are case-sensitive when quoted. Use unquoted uppercase names or verify exact case.

Unsupported data type errors

Symptoms:

Error message: “unsupported conversion from arrow to sdk type”
Specific types mentioned: DECIMAL128, TIME32, DATE32

Solutions:

Some Db2 data types may not be fully supported. Workarounds:

DECIMAL columns: Cast to a supported numeric type:

SELECT CAST(decimal_column AS DOUBLE) AS value FROM table

TIME columns: Cast to VARCHAR or extract components:
SQL
```
SELECT VARCHAR(time_column) AS time_string FROM table
```

DATE columns: Cast to TIMESTAMP:

SELECT TIMESTAMP(date_column) AS time FROM table

Query timeout

Symptoms:

Query fails with a timeout error
Long-running or heavy queries are cancelled before completion

Solutions:

Increase the Query Timeout in the data source configuration: open your data source Settings, expand Additional settings, then set Query Timeout. Default is 30 seconds; maximum is 600 seconds.
Optimize your query (add filters, limit result set, add indexes) so it completes within the timeout.
Narrow the dashboard time range or use FETCH FIRST n ROWS ONLY to reduce data scanned.

Query syntax errors

Symptoms:

Error message indicates SQL syntax error
Query fails immediately after execution

Solutions:

Verify your SQL syntax is valid for IBM Db2.
Check that all table and column names exist.
Ensure string values are enclosed in single quotes.
For time series queries, verify the time column contains valid timestamp values.

SSL/TLS errors

SSL connection failures

Symptoms:

Connection fails when SSL is enabled
Error messages mention SSL, TLS, or certificate issues

Solutions:

Verify your Db2 server is configured for SSL connections.
Try disabling SSL in the data source configuration to test basic connectivity.
Check that the Db2 server’s SSL certificate is valid and not expired.

Performance issues

Slow queries

Symptoms:

Queries take a long time to execute
Dashboard panels load slowly

Solutions:

Add appropriate indexes to your Db2 tables.
Limit the result set using FETCH FIRST n ROWS ONLY.
Narrow the time range in your dashboard.
Optimize your SQL query (avoid SELECT *).
Check Db2 server resources and performance.
If queries often hit the limit, increase Query Timeout in Additional settings (1–600 seconds).

High query latency under concurrent load

Symptoms:

First query per panel is slow, subsequent queries are fast.
Latency spikes when many users run dashboards simultaneously.

Context:

The plugin maintains a per-datasource connection pool (default 50 connections). Each query borrows a connection from the pool and returns it when done, avoiding the overhead of creating a new TCP connection and Db2 authentication for every query.

Solutions:

Increase Connection pool size in Additional settings if you observe connection-wait latency under high concurrency (for example, 50 or more simultaneous queries).

Heavy load on the Db2 server

Symptoms:

The Db2 server shows high CPU or memory usage.
Other applications connecting to the same Db2 server experience degraded performance.

Solutions:

Decrease Connection pool size in Additional settings to limit the number of concurrent connections the plugin holds against the Db2 server.
On self-hosted Grafana, you can also set the default pool size globally for all datasources via the GF_PLUGINS_IBMDB2_DATASOURCE_POOLSIZE environment variable.

Connections are dropped or become stale

Symptoms:

Sporadic “connection closed” errors, especially after idle periods.
Errors mentioning “broken pipe” or “connection reset”.

Solutions:

Reduce Max connection lifetime in Additional settings to a value shorter than the Db2 server’s idle connection timeout. For example, if Db2 closes idle connections after 5 minutes, set this to 240 (4 minutes) to force pool refresh before that happens. The default is 300 seconds; set to 0 for no limit.