{"record":{"id":"45f6cd2374aed3db","repo":"cube-js/cube","slug":"unable-to-describe-table","errorCode":null,"errorMessage":"Unable to describe table","messagePattern":"Unable to describe table","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/cubejs-clickhouse-driver/src/ClickHouseDriver.ts","lineNumber":579,"sourceCode":"\n  public async isUnloadSupported() {\n    return !!this.config.exportBucket;\n  }\n\n  /**\n   * Returns an array of queried fields meta info.\n   */\n  public async queryColumnTypes(sql: string, params: unknown[]): Promise<TableStructure> {\n    // For DESCRIBE we expect that each row would have special structure\n    // See https://clickhouse.com/docs/en/sql-reference/statements/describe-table\n    // TODO complete this type\n    type DescribeRow = {\n      name: string,\n      type: string\n    };\n    const columns = await this.query<DescribeRow>(`DESCRIBE ${sql}`, params);\n    if (!columns) {\n      throw new Error('Unable to describe table');\n    }\n\n    return columns.map((column) => ({\n      name: column.name,\n      type: this.toGenericType(column.type),\n    }));\n  }\n\n  // This is only for use in tests\n  public override async createTableRaw(query: string): Promise<void> {\n    await this.command(query);\n  }\n\n  public override async createTable(quotedTableName: string, columns: TableColumn[]) {\n    const createTableSql = this.createTableSql(quotedTableName, columns);\n    try {\n      await this.command(createTableSql);\n    } catch (e) {","sourceCodeStart":561,"sourceCodeEnd":597,"githubUrl":"https://github.com/cube-js/cube/blob/7d981676b36392fec34088b9afab6bdcad40207c/packages/cubejs-clickhouse-driver/src/ClickHouseDriver.ts#L561-L597","documentation":"queryColumnTypes() runs `DESCRIBE (<sql>)` against ClickHouse to infer column names/types, and throws when the query returns no columns (falsy result). It is called by the types()/downloadQueryResults metadata path, so a table-less or non-selectable query breaks type inference.","triggerScenarios":"Calling types() (e.g. during pre-aggregation load checks) with a query whose DESCRIBE yields no rows/columns — e.g. an empty result set from DESCRIBE, permission-restricted metadata, or a subquery ClickHouse cannot describe.","commonSituations":"Querying a view or table the ClickHouse user lacks DESCRIBE privileges on; queries against empty/temporary tables in some ClickHouse versions returning no metadata; malformed sql wrapped by the caller; mocked drivers in tests returning undefined from query().","solutions":["Grant the ClickHouse user DESCRIBE/metadata privileges on the underlying tables and database","Run `DESCRIBE (<sql>)` manually in clickhouse-client to see why it returns nothing","Verify the sql/params passed to types() reference existing tables/views","Upgrade driver/ClickHouse — older versions could return empty metadata for certain engines","If using a custom/mock driver implementation, ensure query() resolves with the rows array rather than undefined"],"exampleFix":"// before (test mock)\nquery: async () => undefined\n// after\nquery: async () => [{ name: 'id', type: 'UInt64' }]","handlingStrategy":"validation","validationCode":"// Ensure the user can describe the target table before calling types()\nawait clickhouseClient.exec({ query: `DESCRIBE TABLE my_db.my_table` });","typeGuard":"const isDescribable = (cols: unknown): cols is Array<{ name: string; type: string }> =>\n  Array.isArray(cols) && cols.length > 0 && cols.every(c => typeof c?.name === 'string' && typeof c?.type === 'string');","tryCatchPattern":"try { return await driver.downloadQueryResults(q, v); }\ncatch (e) {\n  if (String(e.message) === 'Unable to describe table') throw new Error('Check DESCRIBE privileges and that the query targets existing tables', { cause: e });\n  throw e;\n}","preventionTips":["GRANT DESCRIBE/metadata privileges to the Cube ClickHouse user","Verify referenced tables/views exist in the target database","Run the DESCRIBE wrapper query manually when debugging"],"tags":["clickhouse","metadata","permissions","schema-introspection"],"backgroundTag":"table-describe-failed","analyzedSha":"7d981676b36392fec34088b9afab6bdcad40207c","analyzedAt":"2026-09-02T03:45:10.400Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}