{"record":{"id":"e6b18027e844a00b","repo":"cube-js/cube","slug":"unload-is-not-configured-please-define-cubejs-aws","errorCode":null,"errorMessage":"Unload is not configured. Please define CUBEJS_AWS_S3_OUTPUT_LOCATION env var ","messagePattern":"Unload is not configured\\. Please define CUBEJS_AWS_S3_OUTPUT_LOCATION env var ","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/cubejs-athena-driver/src/AthenaDriver.ts","lineNumber":448,"sourceCode":"      }\n    }\n  }\n\n  /**\n   * Save pre-aggregation data into a temp table.\n   * Returns a cancelable promise that will stop the Athena query on cancel.\n   */\n  public loadPreAggregationIntoTable(\n    preAggregationTableName: string,\n    loadSql: string,\n    params: any,\n  ): MaybeCancelablePromise<any> {\n    let qid: AthenaQueryId | null = null;\n    let cancelled = false;\n\n    const promise: any = (async () => {\n      if (this.config.S3OutputLocation === undefined) {\n        throw new Error('Unload is not configured. Please define CUBEJS_AWS_S3_OUTPUT_LOCATION env var ');\n      }\n      qid = await this.startQuery(loadSql, params);\n      if (cancelled) {\n        await this.stopQuery(qid);\n        throw new Error('Query was cancelled');\n      }\n      await this.waitForSuccess(qid, () => cancelled);\n    })();\n\n    promise.cancel = async () => {\n      cancelled = true;\n      if (qid) {\n        await this.stopQuery(qid);\n      }\n    };\n\n    return promise;\n  }","sourceCodeStart":430,"sourceCodeEnd":466,"githubUrl":"https://github.com/cube-js/cube/blob/7d981676b36392fec34088b9afab6bdcad40207c/packages/cubejs-athena-driver/src/AthenaDriver.ts#L430-L466","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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)"],"exampleFix":"// before\nCUBEJS_DB_TYPE=athena  # no output location\n// after\nCUBEJS_AWS_S3_OUTPUT_LOCATION=s3://my-cube-export-bucket/athena-results/","handlingStrategy":"validation","validationCode":"function assertAthenaUnloadConfigured(driver) {\n  if (!process.env.CUBEJS_AWS_S3_OUTPUT_LOCATION) {\n    throw new Error('CUBEJS_AWS_S3_OUTPUT_LOCATION must be set for Athena UNLOAD')\n  }\n}","typeGuard":"function hasS3OutputLocation(c: any): c is { S3OutputLocation: string } {\n  return typeof c?.S3OutputLocation === 'string' && c.S3OutputLocation.startsWith('s3://')\n}","tryCatchPattern":"try {\n  await driver.loadPreAggregationIntoTable(table, loadSql, params)\n} catch (e) {\n  if (/S3_OUTPUT_LOCATION/.test(e.message)) {\n    console.error('Set CUBEJS_AWS_S3_OUTPUT_LOCATION to enable Athena unload')\n  }\n  throw e\n}","preventionTips":["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"],"tags":["athena","configuration","s3","pre-aggregations"],"backgroundTag":"missing-env-var","analyzedSha":"7d981676b36392fec34088b9afab6bdcad40207c","analyzedAt":"2026-09-02T03:45:10.400Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}