{"record":{"id":"5e278682e0254a34","repo":"cube-js/cube","slug":"unload-is-not-configured-5e2786","errorCode":null,"errorMessage":"Unload is not configured","messagePattern":"Unload is not configured","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/cubejs-clickhouse-driver/src/ClickHouseDriver.ts","lineNumber":620,"sourceCode":"\n  /**\n   * We use unloadWithoutTempTable strategy\n   */\n  public async unload(_tableName: string, options: UnloadOptions): Promise<DownloadTableCSVData> {\n    if (!options.query?.sql) {\n      throw new Error('Query must be defined in options');\n    }\n\n    return this.unloadFromQuery(\n      options.query?.sql,\n      options.query?.params,\n      options\n    );\n  }\n\n  public async unloadFromQuery(sql: string, params: unknown[], _options: UnloadOptions): Promise<DownloadTableCSVData> {\n    if (!this.config.exportBucket) {\n      throw new Error('Unload is not configured');\n    }\n\n    const types = await this.queryColumnTypes(`(${sql})`, params);\n    const { bucketName, path } = this.parseBucketUrl(this.config.exportBucket.bucketName);\n    const exportPrefix = path ? `${path}/${uuidv4()}` : uuidv4();\n\n    const formattedQuery = sqlstring.format(`\n      INSERT INTO FUNCTION\n         s3(\n             'https://${bucketName}.s3.${this.config.exportBucket.region}.amazonaws.com/${exportPrefix}/export.csv.gz',\n             '${this.config.exportBucket.keyId}',\n             '${this.config.exportBucket.secretKey}',\n             'CSV'\n          )\n      ${sql}\n    `, params);\n\n    await this.command(formattedQuery);","sourceCodeStart":602,"sourceCodeEnd":638,"githubUrl":"https://github.com/cube-js/cube/blob/7d981676b36392fec34088b9afab6bdcad40207c/packages/cubejs-clickhouse-driver/src/ClickHouseDriver.ts#L602-L638","documentation":"unloadFromQuery() exports query results to the configured export bucket; this error is thrown when the driver was constructed without config.exportBucket, meaning unload-to-bucket was never configured. Configuration, not the query, is the problem.","triggerScenarios":"Calling unload()/unloadFromQuery() (e.g. pre-aggregation unload strategy enabled) while EXPORT_BUCKET_TYPE / EXPORT_BUCKET_NAME envs are unset, so this.config.exportBucket is undefined.","commonSituations":"Setting loadPreAggregationsToExportBucket (or similar strategy) without providing bucket credentials; env vars present in dev but missing in the deployment environment; dataSource-scoped env mismatch.","solutions":["Configure the export bucket: set EXPORT_BUCKET_TYPE, EXPORT_BUCKET_NAME, EXPORT_BUCKET_AWS_KEY, EXPORT_BUCKET_AWS_SECRET envs and restart Cube","Disable the unload/export strategy (e.g. remove loadPreAggregationsToExportBucket from pre-aggregation options) if bucket export is not needed","Confirm env vars are present in the runtime environment (containers often strip them)","Verify the ClickHouseDriver instance is constructed with the expected dataSource so scoped env vars resolve"],"exampleFix":"// before\n# no bucket config, but unload requested -> 'Unload is not configured'\n// after\nEXPORT_BUCKET_TYPE=s3\nEXPORT_BUCKET_NAME=my-bucket\nEXPORT_BUCKET_AWS_KEY=AKIA...\nEXPORT_BUCKET_AWS_SECRET=...","handlingStrategy":"validation","validationCode":"if (!process.env.EXPORT_BUCKET_TYPE || !process.env.EXPORT_BUCKET_NAME) {\n  throw new Error('Unload requested but export bucket is not configured (EXPORT_BUCKET_TYPE/EXPORT_BUCKET_NAME)');\n}","typeGuard":"const unloadConfigured = (cfg: ClickHouseDriverConfiguration): boolean => Boolean(cfg.exportBucket);","tryCatchPattern":"try { return await driver.unload(table, options); }\ncatch (e) {\n  if (String(e.message) === 'Unload is not configured') throw new Error('Set EXPORT_BUCKET_* envs or disable the unload strategy', { cause: e });\n  throw e;\n}","preventionTips":["Enable the unload strategy only when export bucket envs are present","Check envs exist in the runtime environment, not just locally","Keep bucket config consistent across environments"],"tags":["configuration","env-var","clickhouse","unload","export-bucket"],"backgroundTag":"unload-not-configured","analyzedSha":"7d981676b36392fec34088b9afab6bdcad40207c","analyzedAt":"2026-09-02T03:45:10.400Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}