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