Skip to content

SAP HANA Troubleshooting

Most failures while creating or running a SAP HANA datastore fall into three categories: network, credentials, and privileges. The table below maps each common error message returned by the SAP HANA JDBC driver to its likely cause and a concrete fix.

Common Errors

Error message Likely cause Fix
Cannot connect to jdbc:sap://...: connection refused The host or port is wrong, or a firewall blocks the dataplane from reaching HANA. Verify the Host and Port values against the SAP HANA Cockpit (Cloud) or hdbsql -i <instance> -d SYSTEMDB output (on-prem). Confirm the dataplane subnet can reach the SQL port.
Connection failed: java.net.SocketTimeoutException Connection request reached the network but the HANA endpoint did not respond before the JDBC timeout. Check whether HANA is online and whether IP allowlists or VPC routing forwards the request to the right tenant.
Sql exception: invalid username or password (10) Credentials are wrong, or the user is locked. Re-enter the Username and Password (mind trailing spaces). On HANA Cloud, unlock the user from the Cockpit; on-prem, use ALTER USER <name> ACTIVATE USER NOW.
User is forced to change password on first logon The HANA user was created without NO FORCE_FIRST_PASSWORD_CHANGE. Log into HANA once with the user (for example via hdbsql or DBeaver) and change the password, then update the Qualytics connection with the new password.
Sql exception: invalid schema name: <SCHEMA> The schema does not exist, or the connection user has no privilege to see it. Confirm the schema name (HANA stores unquoted names in upper case) and grant SELECT on the schema as described in Permissions.
Sql exception: invalid table name: <TABLE> The table was renamed or dropped between catalog and the next operation, or the user lost SELECT on it. Trigger a manual Sync on the datastore to refresh metadata. If the table still does not appear, re-grant SELECT and re-sync.
Error referencing an unavailable or unreachable tenant database The Database field references a tenant that is stopped, dropped, or unreachable from the port you supplied. Check the tenant in HANA Cockpit. Either start the tenant or switch the connection to a tenant currently online. On HANA Cloud, leave Database blank: the tenant is encoded in the hostname.
Sql exception: not authorized The HANA user is missing a privilege that the operation needs (e.g., SELECT on a system view, or on a target table). Re-check the privilege list in Permissions and grant the missing one. Profile and scan failures usually mean SELECT on the target table is missing; empty dropdowns usually mean SELECT on a SYS.* view is missing.

Detailed Notes

Connectivity failures

If the wrapped error mentions connection refused, SocketTimeoutException, or Unknown host, the JDBC driver never reached HANA. Investigate from the network outward:

  • Verify the Host value resolves from the dataplane (nslookup, dig).
  • Confirm the Port matches the SQL port of the tenant (HANA Cloud: 443; on-premises: 3<instance>15 or the tenant-specific port).
  • Check firewall rules, security groups, and private endpoint configurations between the Qualytics dataplane and HANA.

Tip

HANA Cloud endpoints require IP allowlisting in the Cockpit's Connections section. Add the egress IP range of the Qualytics dataplane there before retrying.

Port mismatch on TLS endpoints

If the wrapped error references SSL Exception or certificate validation failed against a HANA Cloud endpoint, the most common cause is a non-TLS port. HANA Cloud uses port 443; pointing at any other port will fail the TLS handshake before the certificate is even inspected. Verify the Port field against the value shown in the HANA Cockpit.

Authentication errors

If the wrapped error mentions invalid username or password, user is locked, or forced to change password, the credentials reached HANA but HANA rejected them. Adjust the credentials, not the privileges:

  • Confirm the Username and Password values were copied without whitespace or trailing newlines.
  • HANA stores unquoted user names in upper case. Submitting qualytics_reader and QUALYTICS_READER connects to the same user, but a user created with double-quotes (CREATE USER "lower_user") requires the exact case.
  • A user forced to change password on first logon must complete that change outside Qualytics before the connection succeeds.

Schema and tenant errors

If the wrapped error mentions an invalid schema, invalid table, or unavailable tenant, the connection reached HANA but the target object is not visible or not online:

  • Check the Database field. Leave it blank for HANA Cloud (the tenant is in the hostname). For on-premises HANA, set it to the tenant database the user lives in.
  • Use SELECT * FROM SYS.M_DATABASES on the system database to list tenants and confirm they are online.
  • Grant the user SELECT on the schema, or list the granted schemas with SELECT SCHEMA_NAME FROM SYS.GRANTED_PRIVILEGES WHERE GRANTEE = '<USER>' AND OBJECT_TYPE = 'SCHEMA'. For privileges inherited through roles, query SYS.EFFECTIVE_PRIVILEGES instead.

Privilege errors

If the wrapped error mentions not authorized, the user is authenticated but is missing the privilege required for the specific call:

  • Empty Schema dropdown: missing SELECT on SYS.SCHEMAS or SYS.TABLES.
  • Empty Container dropdown after sync: missing schema-level or table-level SELECT on application objects.
  • Profile or scan failure on a single table: missing SELECT on that specific table or view.

Re-check the privilege list in Permissions and grant only the privileges actually needed; administrative roles such as DATA ADMIN should not be assigned to the connection user.

Diagnostic order

Symptom Layer Where to look
Connection refused, timeout, unknown host Network Hostname, port, firewall, IP allowlist
Invalid username or password, user locked Authentication HANA user state and credentials
Invalid schema, invalid table, tenant unavailable Catalog / Routing Database field, tenant status, schema name casing
Not authorized Authorization Granted privileges on schema, tables, and system views

Investigating in this order avoids chasing privilege changes when the real issue is the wrong port or a stopped tenant.