apache/seatunnel · error · CatalogException

Failed getting table %s

Error message

Failed getting table %s

What it means

ClickhouseCatalog.getTable builds a CatalogTable by querying ClickHouse metadata through its proxy client. Any exception during metadata lookup, option building, or connection is wrapped in a CatalogException with 'Failed getting table <name>'. It signals the catalog could not read the table's schema or metadata from the ClickHouse server.

Source

Thrown at seatunnel-connectors-v2/connector-clickhouse/src/main/java/org/apache/seatunnel/connectors/seatunnel/clickhouse/catalog/ClickhouseCatalog.java:138

                                    (long) column.getEstimatedLength(),
                                    column.getScale(),
                                    column.isNullable(),
                                    null,
                                    null,
                                    null,
                                    sourceTypeMap.get(column.getColumnName())));

            TableIdentifier tableIdentifier =
                    TableIdentifier.of(
                            catalogName, tablePath.getDatabaseName(), tablePath.getTableName());
            return CatalogTable.of(
                    tableIdentifier,
                    builder.build(),
                    buildConnectorOptions(tablePath),
                    Collections.emptyList(),
                    "");
        } catch (Exception e) {
            throw new CatalogException(
                    String.format("Failed getting table %s", tablePath.getFullName()), e);
        }
    }

    @Override
    public void createTable(TablePath tablePath, CatalogTable table, boolean ignoreIfExists)
            throws TableAlreadyExistException, DatabaseNotExistException, CatalogException {
        log.debug("Create table :{}.{}", tablePath.getDatabaseName(), tablePath.getTableName());
        proxy.createTable(
                tablePath.getDatabaseName(),
                tablePath.getTableName(),
                template,
                table.getComment(),
                table.getTableSchema());
    }

    @Override
    public void dropTable(TablePath tablePath, boolean ignoreIfNotExists)

View on GitHub (pinned to cf67b549a7)

Solutions

1. Verify the TablePath database and table names exist in ClickHouse (SHOW TABLES FROM <db>) and match the config exactly
2. Check the ClickHouse user has SELECT/DESCRIBE privileges on the table
3. Confirm connectivity (host, port, credentials) used by the catalog's proxy client and retry
4. Catch CatalogException and, if the cause is missing table, route to TableNotExistException handling or create the table first

Example fix

// before
CatalogTable table = catalog.getTable(tablePath); // throws CatalogException if missing
// after
if (catalog.tableExists(tablePath)) {
    CatalogTable table = catalog.getTable(tablePath);
} else {
    throw new TableNotExistException(catalogName, tablePath);
}

if (!catalog.tableExists(tablePath)) {
    throw new TableNotExistException(catalogName, tablePath);
}
// also verify connectivity
boolean reachable = pingClickHouse(catalogOptions);

try {
    CatalogTable table = catalog.getTable(tablePath);
} catch (CatalogException e) {
    Throwable cause = e.getCause();
    if (cause != null && String.valueOf(cause.getMessage()).contains("UNKNOWN_TABLE")) {
        throw new TableNotExistException(catalogName, tablePath, cause);
    }
    throw e;
}

When it happens

Trigger: Calling getTable(tablePath) (e.g. via catalogTable) when the table does not exist, the user lacks privileges to describe it, the ClickHouse server is unreachable, or the database/table name is wrong.

Common situations: Typo in database or table name in the catalog config; table dropped between exists-check and getTable; insufficient ClickHouse grants (no DESCRIBE access); network/auth failures to the ClickHouse HTTP or native port.

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

• LIST_DATABASES_FAILED
• LIST_TABLES_FAILED
• Truncate table failed
• Failed EXECUTE SQL in catalog %s
• Unsupported action type:

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/135a3d73fab5b39b. Report an issue: GitHub.