apache/seatunnel · error · HbaseConnectorException
DATABASE_QUERY_EXCEPTION
DATABASE_QUERY_EXCEPTION
Error message
DATABASE_QUERY_EXCEPTION
What it means
databaseExists() lists HBase namespace descriptors via admin.listNamespaceDescriptors() to check if a namespace exists. If that admin call throws an IOException, it is wrapped as HbaseConnectorException with DATABASE_QUERY_EXCEPTION. It is used by createTable before creating the namespace.
Solutions
- Verify the HBase cluster and master are healthy (HBase UI / hbck)
- Check that the connected user has permission to list namespaces
- Inspect the wrapped IOException cause for RPC timeouts and tune hbase.rpc.timeout / client retries
- Retry the operation after confirming connectivity
Example fix
// before
try {
return Arrays.stream(admin.listNamespaceDescriptors())
.anyMatch(d -> d.getName().equals(databaseName));
} catch (IOException e) {
throw new HbaseConnectorException(HbaseConnectorErrorCode.DATABASE_QUERY_EXCEPTION, ...);
}
// after
try {
return Arrays.stream(admin.listNamespaceDescriptors())
.anyMatch(d -> d.getName().equals(databaseName));
} catch (IOException e) {
log.warn("Namespace list failed, retrying", e);
return Arrays.stream(admin.listNamespaceDescriptors())
.anyMatch(d -> d.getName().equals(databaseName));
} Defensive patterns
Strategy: try-catch
Validate before calling
// verify admin/cluster health first
try (Connection c = ConnectionFactory.createConnection(conf); Admin a = c.getAdmin()) {
a.clusterStatus(); // throws early if cluster is not reachable
} Try / catch
try {
exists = client.databaseExists(ns);
} catch (HbaseConnectorException e) {
if (e.getErrorCode() == HbaseConnectorErrorCode.DATABASE_QUERY_EXCEPTION) {
// check cluster health / permissions, then retry
} else throw e;
} Prevention
- Check master availability and user ACLs on namespaces before catalog operations
- Tune hbase.rpc.timeout and client retry settings for loaded clusters
- Call listDatabases once and cache results instead of repeated admin calls
When it happens
Trigger: Calling HbaseClient.databaseExists() (directly or via createTable) when the Admin call to list namespaces fails: connection dropped, RPC timeout, permission denied on the namespace listing, or master not available.
Common situations: HBase master temporarily unavailable or restarting; RPC timeout under load; user lacks permission to list namespaces; transient network partition between SeaTunnel worker and cluster.
Understand the failure class
Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.
Related errors
AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10).
Data as JSON: /api/errors/4ead46e41e0f5a06.
Report an issue: GitHub.
Appendix: source
Thrown at seatunnel-connectors-v2/connector-hbase/src/main/java/org/apache/seatunnel/connectors/seatunnel/hbase/client/HbaseClient.java:133
} catch (IOException e) {
String errorMsg = "Build Hbase connection failed.";
throw new HbaseConnectorException(
HbaseConnectorErrorCode.CONNECTION_FAILED, errorMsg, e);
}
}
/**
* Check if a database exists.
*
* @param databaseName database name
* @return true if the database exists, false otherwise
*/
public boolean databaseExists(String databaseName) {
try {
return Arrays.stream(admin.listNamespaceDescriptors())
.anyMatch(descriptor -> descriptor.getName().equals(databaseName));
} catch (IOException e) {
throw new HbaseConnectorException(
HbaseConnectorErrorCode.DATABASE_QUERY_EXCEPTION,
HbaseConnectorErrorCode.DATABASE_QUERY_EXCEPTION.getErrorMessage(),
e);
}
}
/**
* List all databases.
*
* @return List of database names
*/
public List<String> listDatabases() {
try {
return Arrays.stream(admin.listNamespaceDescriptors())
.map(NamespaceDescriptor::getName)
.collect(Collectors.toList());
} catch (IOException e) {
throw new HbaseConnectorException(View on GitHub (pinned to cf67b549a7)