{"record":{"id":"244ca647a6db708c","repo":"apache/seatunnel","slug":"table-schema-get-failed-244ca6","errorCode":"TABLE_SCHEMA_GET_FAILED","errorMessage":"Cannot get table schema from clickhouse","messagePattern":"Cannot get table schema from clickhouse","errorType":"error_code","errorClass":"ClickhouseConnectorException","httpStatus":null,"severity":"error","filePath":"seatunnel-connectors-v2/connector-clickhouse/src/main/java/org/apache/seatunnel/connectors/seatunnel/clickhouse/util/ClickhouseProxy.java","lineNumber":172,"sourceCode":"    public Map<String, String> getClickhouseTableSchema(String table) {\n        ClickHouseRequest<?> request = getClickhouseConnection();\n        return getClickhouseTableSchema(request, table);\n    }\n\n    public Map<String, String> getClickhouseTableSchema(\n            ClickHouseRequest<?> request, String table) {\n        String sql = \"desc \" + table;\n        Map<String, String> schema = new LinkedHashMap<>();\n        try (ClickHouseResponse response = request.query(sql).executeAndWait()) {\n            response.records()\n                    .forEach(\n                            r -> {\n                                if (!\"MATERIALIZED\".equals(r.getValue(2).asString())) {\n                                    schema.put(r.getValue(0).asString(), r.getValue(1).asString());\n                                }\n                            });\n        } catch (ClickHouseException e) {\n            throw new ClickhouseConnectorException(\n                    CommonErrorCodeDeprecated.TABLE_SCHEMA_GET_FAILED,\n                    \"Cannot get table schema from clickhouse\",\n                    e);\n        }\n        return schema;\n    }\n\n    public List<ClickHouseColumn> getClickHouseColumns(String table) {\n        String sql = \"SELECT * FROM \" + table + \" WHERE 1 = 0\";\n        try (ClickHouseResponse response = this.clickhouseRequest.query(sql).executeAndWait()) {\n            return response.getColumns();\n\n        } catch (ClickHouseException e) {\n            throw new ClickhouseConnectorException(\n                    CommonErrorCodeDeprecated.TABLE_SCHEMA_GET_FAILED,\n                    \"Cannot get table schema from clickhouse\",\n                    e);\n        }","sourceCodeStart":154,"sourceCodeEnd":190,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-clickhouse/src/main/java/org/apache/seatunnel/connectors/seatunnel/clickhouse/util/ClickhouseProxy.java#L154-L190","documentation":"ClickhouseProxy.getClickhouseTableSchema issues a DESCRIBE-style query against system.columns and wraps any ClickHouseException into a ClickhouseConnectorException with CommonErrorCodeDeprecated.TABLE_SCHEMA_GET_FAILED. It means the connector could not read the column name/type pairs for the requested table.","triggerScenarios":"Calling getClickhouseTableSchema (directly or via getClickhouseTable) when the table does not exist, the database name is wrong, or the query fails due to connection/auth/timeout errors surfaced as ClickHouseException.","commonSituations":"Typo in table name in config; user lacks SELECT privilege on the table; ClickHouse server unreachable or restarted mid-query; materialized views referenced without permissions.","solutions":["Confirm the table exists: SELECT name FROM system.tables WHERE database='<db>' AND name='<table>';","Validate database and table names in the connector config (quote identifiers containing dots)","Grant the ClickHouse user SELECT privilege on the table and system.columns","Check network connectivity and credentials in the ClickHouse URL/options","Retry if the failure was a transient ClickHouseException (server restart, timeout)"],"exampleFix":"// before\nMap<String,String> schema = proxy.getClickhouseTableSchema(request, \"events\"); // table in db 'prod', not default\n// after\nMap<String,String> schema = proxy.getClickhouseTableSchema(request, \"prod.events\"); // fully qualified name","handlingStrategy":"validation","validationCode":"if (!proxy.tableExists(request, database, table)) {\n    throw new IllegalArgumentException(database + \".\" + table + \" does not exist\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    Map<String,String> schema = proxy.getClickhouseTableSchema(request, table);\n} catch (ClickhouseConnectorException e) {\n    // inspect cause ClickHouseException for auth/connectivity; retry once on transient errors\n    throw new RuntimeException(\"Schema read failed: \" + e.getMessage(), e);\n}","preventionTips":["Use fully qualified database.table names","Grant SELECT on the table and system.columns before running jobs","Pre-check existence with tableExists before reading schema","Monitor ClickHouse availability during job startup"],"tags":["clickhouse","schema","metadata"],"backgroundTag":"schema-validation-failed","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}