Athena job timeout reached ${this.config.pollTimeout}ms

Error message

Athena job timeout reached ${this.config.pollTimeout}ms

What it means

waitForSuccess polls Athena until the elapsed time exceeds this.config.pollTimeout; when the loop exits without a SUCCEEDED state, the driver calls stopQuery (best-effort) and throws a timeout error including the configured millisecond value. It means the query ran longer than the driver was willing to wait.

Source

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

    return status === 'SUCCEEDED';
  }

  protected async waitForSuccess(qid: AthenaQueryId, isCancelled?: () => boolean): Promise<void> {
    const startedTime = Date.now();
    for (let i = 0; Date.now() - startedTime <= this.config.pollTimeout; i++) {
      if (isCancelled?.()) {
        throw new Error('Query was cancelled');
      }
      if (await this.checkStatus(qid)) {
        return;
      }
      await pausePromise(
        Math.min(this.config.pollMaxInterval, 500 * i)
      );
    }
    await this.stopQuery(qid);
    throw new Error(
      `Athena job timeout reached ${this.config.pollTimeout}ms`
    );
  }

  // Best-effort: a failure to stop must never bubble up to the caller,
  // which has already abandoned the query.
  protected async stopQuery(qid: AthenaQueryId): Promise<void> {
    try {
      await this.athena.stopQueryExecution({ QueryExecutionId: qid.QueryExecutionId });
    } catch (e) {
      this.logger?.('Failed to stop Athena query', {
        queryExecutionId: qid.QueryExecutionId,
        error: (e as Error).message ?? String(e),
      });
    }
  }

  protected async viewsSchema(tablesSchema: DatabaseStructure): Promise<DatabaseStructure> {

View on GitHub (pinned to 7d981676b3)

Solutions

Increase pollTimeout in the AthenaDriver config to cover your longest expected query.
Reduce the cost of schema introspection (restrict the schema option, avoid excessive views) so tablesSchema completes faster.
Optimize the underlying SQL / add Athena partitions to shrink runtime.
Check the Athena workgroup for queuing/concurrency limits that delay execution.

Example fix

// before
const driver = new AthenaDriver({ database: 'mydb', S3OutputLocation: 's3://bucket/out/' });
// after
const driver = new AthenaDriver({ database: 'mydb', S3OutputLocation: 's3://bucket/out/', pollTimeout: 600000, pollMaxInterval: 2000 });

Defensive patterns

Strategy: validation

Validate before calling

// Size your pollTimeout to your slowest query workload
const pollTimeout = process.env.ATHENA_POLL_TIMEOUT
  ? parseInt(process.env.ATHENA_POLL_TIMEOUT, 10)
  : 600000;
if (!(pollTimeout > 0)) throw new Error('ATHENA_POLL_TIMEOUT must be positive ms');

Type guard

function isAthenaTimeout(e: unknown): boolean {
  return e instanceof Error && /^Athena job timeout reached \d+ms$/.test(e.message);
}

Try / catch

try {
  await driver.query(sql);
} catch (e) {
  if (isAthenaTimeout(e)) {
    // consider retrying with larger pollTimeout or optimizing the query
  } else throw e;
}

Prevention

Set pollTimeout explicitly (e.g. 10 minutes) instead of relying on the default.
Benchmark your heaviest pre-aggregation build and size pollTimeout accordingly.
Limit schema introspection cost by setting the schema option and avoiding unnecessary views.
Partition large tables so Athena scans stay fast.

When it happens

Trigger: Any Athena query (unload, schema scan, queryColumnTypes) still RUNNING/QUEUED after pollTimeout ms of polling — e.g. default pollTimeout with a large unload or a schema scan over hundreds of tables.

Common situations: Large pre-aggregation loads in Athena; deep table scans triggering the tablesSchema/ viewsSchema introspection on schema compile; Athena queue backlogs in busy workgroups making even small queries exceed the timeout.

Understand the failure class

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

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