apache/seatunnel · error · HbaseConnectorException

TABLE_QUERY_EXCEPTION

TABLE_QUERY_EXCEPTION

Error message

HbaseConnectorErrorCode.TABLE_QUERY_EXCEPTION.getErrorMessage()

What it means

tableExists(tableName) calls admin.tableExists(TableName.valueOf(tableName)); an IOException (RPC/connection failure) is wrapped as HbaseConnectorException with TABLE_QUERY_EXCEPTION. Note: a table simply not existing returns false — this error only fires on infrastructure failures.

Solutions

1. Verify cluster connectivity and master availability before running jobs
2. Validate the table name format (namespace:table or default namespace) and allowed characters
3. Inspect the wrapped IOException for the underlying cause and tune hbase client timeouts/retries
4. Retry the existence check after transient failures

// validate name format before the call
if (tableName == null || tableName.isEmpty() || tableName.contains(" ")) {
    throw new IllegalArgumentException("Invalid HBase table name: " + tableName);
}

int attempts = 0;
while (true) {
    try { return client.tableExists(name); }
    catch (HbaseConnectorException e) {
        if (e.getErrorCode() == HbaseConnectorErrorCode.TABLE_QUERY_EXCEPTION && ++attempts < 3) {
            Thread.sleep(1000L * attempts);
            continue;
        }
        throw e;
    }
}

When it happens

Trigger: Calling tableExists() (directly or via createTable/getTableSplits/source validation) when admin.tableExists throws IOException: connection dropped, master unavailable, RPC timeout, or invalid table name causing server-side errors.

Common situations: HBase master restarting while a job starts; network partition; wrong cluster endpoint from missing/bad hbase-site.xml; TableName string malformed (contains illegal characters) causing conversion errors.

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

• DATABASE_QUERY_EXCEPTION
• NAMESPACE_CREATE_EXCEPTION
• TABLE_CREATE_EXCEPTION
• TABLE_EXISTS_EXCEPTION
• CONNECTION_FAILED

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/79afc69e2daf5e5d. 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:187

        } catch (IOException e) {
            throw new HbaseConnectorException(
                    HbaseConnectorErrorCode.DATABASE_QUERY_EXCEPTION,
                    HbaseConnectorErrorCode.DATABASE_QUERY_EXCEPTION.getErrorMessage(),
                    e);
        }
    }

    /**
     * Check if a table exists.
     *
     * @param tableName table name
     * @return true if the table exists, false otherwise
     */
    public boolean tableExists(String tableName) {
        try {
            return admin.tableExists(TableName.valueOf(tableName));
        } catch (IOException e) {
            throw new HbaseConnectorException(
                    HbaseConnectorErrorCode.TABLE_QUERY_EXCEPTION,
                    HbaseConnectorErrorCode.TABLE_QUERY_EXCEPTION.getErrorMessage(),
                    e);
        }
    }

    /**
     * Create a table.
     *
     * @param databaseName database name
     * @param tableName table name
     * @param columnFamilies column families
     * @param ignoreIfExists ignore if the table already exists
     */
    public void createTable(
            String databaseName,
            String tableName,
            List<String> columnFamilies,

View on GitHub (pinned to cf67b549a7)