cube-js/cube · error

Unload is not configured

Error message

Unload is not configured

What it means

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.

Source

Thrown at packages/cubejs-clickhouse-driver/src/ClickHouseDriver.ts:620

  /**
   * We use unloadWithoutTempTable strategy
   */
  public async unload(_tableName: string, options: UnloadOptions): Promise<DownloadTableCSVData> {
    if (!options.query?.sql) {
      throw new Error('Query must be defined in options');
    }

    return this.unloadFromQuery(
      options.query?.sql,
      options.query?.params,
      options
    );
  }

  public async unloadFromQuery(sql: string, params: unknown[], _options: UnloadOptions): Promise<DownloadTableCSVData> {
    if (!this.config.exportBucket) {
      throw new Error('Unload is not configured');
    }

    const types = await this.queryColumnTypes(`(${sql})`, params);
    const { bucketName, path } = this.parseBucketUrl(this.config.exportBucket.bucketName);
    const exportPrefix = path ? `${path}/${uuidv4()}` : uuidv4();

    const formattedQuery = sqlstring.format(`
      INSERT INTO FUNCTION
         s3(
             'https://${bucketName}.s3.${this.config.exportBucket.region}.amazonaws.com/${exportPrefix}/export.csv.gz',
             '${this.config.exportBucket.keyId}',
             '${this.config.exportBucket.secretKey}',
             'CSV'
          )
      ${sql}
    `, params);

    await this.command(formattedQuery);

View on GitHub (pinned to 7d981676b3)

Solutions

1. Configure the export bucket: set EXPORT_BUCKET_TYPE, EXPORT_BUCKET_NAME, EXPORT_BUCKET_AWS_KEY, EXPORT_BUCKET_AWS_SECRET envs and restart Cube
2. Disable the unload/export strategy (e.g. remove loadPreAggregationsToExportBucket from pre-aggregation options) if bucket export is not needed
3. Confirm env vars are present in the runtime environment (containers often strip them)
4. Verify the ClickHouseDriver instance is constructed with the expected dataSource so scoped env vars resolve

Example fix

// before
# no bucket config, but unload requested -> 'Unload is not configured'
// after
EXPORT_BUCKET_TYPE=s3
EXPORT_BUCKET_NAME=my-bucket
EXPORT_BUCKET_AWS_KEY=AKIA...
EXPORT_BUCKET_AWS_SECRET=...

if (!process.env.EXPORT_BUCKET_TYPE || !process.env.EXPORT_BUCKET_NAME) {
  throw new Error('Unload requested but export bucket is not configured (EXPORT_BUCKET_TYPE/EXPORT_BUCKET_NAME)');
}

const unloadConfigured = (cfg: ClickHouseDriverConfiguration): boolean => Boolean(cfg.exportBucket);

try { return await driver.unload(table, options); }
catch (e) {
  if (String(e.message) === 'Unload is not configured') throw new Error('Set EXPORT_BUCKET_* envs or disable the unload strategy', { cause: e });
  throw e;
}

When it happens

Trigger: 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.

Common situations: Setting loadPreAggregationsToExportBucket (or similar strategy) without providing bucket credentials; env vars present in dev but missing in the deployment environment; dataSource-scoped env mismatch.

Related errors

• Unsupported EXPORT_BUCKET_TYPE, supported: ${SUPPORTED_BUCKE
• Unsupported configuration exportBucket, some configuration k
• Query must be defined in options
• Export bucket is not configured.
• Unload is not configured

AI-assisted analysis of cube-js/cube@7d981676b3 (2026-09-02). Data as JSON: /api/errors/5e278682e0254a34. Report an issue: GitHub.