Unload is not configured. Please define CUBEJS_AWS_S3_OUTPUT

Error message

Unload is not configured. Please define CUBEJS_AWS_S3_OUTPUT_LOCATION env var

What it means

loadPreAggregationIntoTable uses Athena UNLOAD, which requires an S3 output location. When config.S3OutputLocation is undefined (i.e. CUBEJS_AWS_S3_OUTPUT_LOCATION was not set), the driver refuses to run and throws this configuration error before starting any query.

Source

Thrown at packages/cubejs-athena-driver/src/AthenaDriver.ts:448

      }
    }
  }

  /**
   * Save pre-aggregation data into a temp table.
   * Returns a cancelable promise that will stop the Athena query on cancel.
   */
  public loadPreAggregationIntoTable(
    preAggregationTableName: string,
    loadSql: string,
    params: any,
  ): MaybeCancelablePromise<any> {
    let qid: AthenaQueryId | null = null;
    let cancelled = false;

    const promise: any = (async () => {
      if (this.config.S3OutputLocation === undefined) {
        throw new Error('Unload is not configured. Please define CUBEJS_AWS_S3_OUTPUT_LOCATION env var ');
      }
      qid = await this.startQuery(loadSql, params);
      if (cancelled) {
        await this.stopQuery(qid);
        throw new Error('Query was cancelled');
      }
      await this.waitForSuccess(qid, () => cancelled);
    })();

    promise.cancel = async () => {
      cancelled = true;
      if (qid) {
        await this.stopQuery(qid);
      }
    };

    return promise;
  }

View on GitHub (pinned to 7d981676b3)

Solutions

Set CUBEJS_AWS_S3_OUTPUT_LOCATION to an existing s3:// bucket/prefix writable by the Athena service
Alternatively pass s3OutputLocation in the AthenaDriver constructor config
Ensure the IAM role has s3 permissions for the output bucket (PutObject on the prefix)

Example fix

// before
CUBEJS_DB_TYPE=athena  # no output location
// after
CUBEJS_AWS_S3_OUTPUT_LOCATION=s3://my-cube-export-bucket/athena-results/

Defensive patterns

Strategy: validation

Validate before calling

function assertAthenaUnloadConfigured(driver) {
  if (!process.env.CUBEJS_AWS_S3_OUTPUT_LOCATION) {
    throw new Error('CUBEJS_AWS_S3_OUTPUT_LOCATION must be set for Athena UNLOAD')
  }
}

Type guard

function hasS3OutputLocation(c: any): c is { S3OutputLocation: string } {
  return typeof c?.S3OutputLocation === 'string' && c.S3OutputLocation.startsWith('s3://')
}

Try / catch

try {
  await driver.loadPreAggregationIntoTable(table, loadSql, params)
} catch (e) {
  if (/S3_OUTPUT_LOCATION/.test(e.message)) {
    console.error('Set CUBEJS_AWS_S3_OUTPUT_LOCATION to enable Athena unload')
  }
  throw e
}

Prevention

Add CUBEJS_AWS_S3_OUTPUT_LOCATION to every environment's config at deploy time
Smoke-test pre-aggregation builds on startup in staging
Validate config on boot with a schema check rather than failing on first unload

When it happens

Trigger: Pre-aggregation unload/loading path executes (pre-aggregations configured to use the export bucket / UNLOAD strategy) while S3OutputLocation is missing from the Athena driver config.

Common situations: CUBEJS_AWS_S3_OUTPUT_LOCATION env var not set in the Cube deployment, driver instantiated with a config object that omits s3OutputLocation, or environment drift between local dev and production.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

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