cube-js/cube · error · Error

Unload is not configured

Error message

Unload is not configured

What it means

unload() implements CSV export via Redshift UNLOAD to S3, which requires the driver's exportBucket configuration. If this.config.exportBucket is undefined, the feature is not configured and the driver refuses to proceed.

Source

Thrown at packages/cubejs-redshift-driver/src/RedshiftDriver.ts:422

    }

    // It's possible that table is external Spectrum table, so we need to query it separately
    const [schema, name] = table.split('.');

    // We might get table from Spectrum schema, so common request via `information_schema.columns`
    // won't return anything. `getColumnsForSpecificTables` is aware of Spectrum tables.
    const columnRes = await this.columnsForExternalTable(schema, name);

    return columnRes.map(c => ({ name: c.column_name, type: this.toGenericType(c.data_type) }));
  }

  public async isUnloadSupported() {
    return !!this.config.exportBucket;
  }

  public async unload(tableName: string, options: UnloadOptions): Promise<DownloadTableCSVData> {
    if (!this.config.exportBucket) {
      throw new Error('Unload is not configured');
    }

    const types = await this.tableColumnTypes(tableName);
    const columns = types.map(t => t.name).join(', ');

    const { bucketType, bucketName, region, unloadArn, keyId, secretKey } = this.config.exportBucket;

    const conn = await this.pool.acquire();

    try {
      const exportPathName = crypto.randomBytes(10).toString('hex');

      const optionsToExport = {
        REGION: `'${region}'`,
        HEADER: '',
        FORMAT: 'CSV',
        GZIP: '',
        MAXFILESIZE: `${options.maxFileSize}MB`

View on GitHub (pinned to 7d981676b3)

Solutions

  1. Configure exportBucket (CUBEJS_EXPORT_BUCKET_TYPE, NAME, AWS_KEY, AWS_SECRET or UNLOAD_ARN) for the Redshift driver
  2. Check isUnloadSupported() before invoking unload and fall back to a different export path
  3. Ensure the driver for the relevant dataSource is the Redshift driver with export config, not a misconfigured instance

Example fix

// before
const data = await driver.unload('pre_agg_table', options);
// after
if (driver.isUnloadSupported()) {
  const data = await driver.unload('pre_agg_table', options);
} else {
  throw new Error('Configure exportBucket to enable Redshift unload export');
}
Defensive patterns

Strategy: try-catch

Validate before calling

if (!driver.isUnloadSupported()) {
  throw new Error('Set exportBucket config to enable Redshift unload');
}

Try / catch

try {
  const data = await driver.unload(tableName, options);
} catch (e) {
  if (e.message === 'Unload is not configured') {
    // fall back to non-UNLOAD export path
  } else throw e;
}

Prevention

When it happens

Trigger: Calling unload(tableName, options) (e.g. via Cube's export feature / DownloadTableCSVData flow) on a driver instance constructed without an exportBucket config block.

Common situations: Calling isUnloadSupported()/unload from custom code without setting exportBucket env vars; orchestrator routes an export to a dataSource whose driver lacks exportBucket config.

Related errors

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