cube-js/cube · error

CubeSQL query timed out after ${timeoutMs}ms

Error message

CubeSQL query timed out after ${timeoutMs}ms

What it means

When the transport reports the CubeSQL request failed with error 'timeout', cubeSql() rethrows a descriptive timeout error including the effective timeout in milliseconds. The default timeout is 5 minutes unless options.timeout overrides it.

Source

Thrown at packages/cubejs-client-core/src/index.ts:813

        if (options?.timezone) {
          cubesqlParams.timezone = options.timezone;
        }

        const request = this.request('cubesql', cubesqlParams);

        return request;
      },
      (response: any) => {
        // TODO: The response is sending both errors and successful results as `error`
        if (!response || !response.error) {
          throw new Error('Invalid response format');
        }

        // Check if this is a timeout or abort error from transport
        if (response.error === 'timeout') {
          const timeoutMs = options?.timeout || 5 * 60 * 1000;
          throw new Error(`CubeSQL query timed out after ${timeoutMs}ms`);
        }

        if (response.error === 'aborted') {
          throw new Error('CubeSQL query was aborted');
        }

        const [schema, ...data] = response.error.split('\n');

        let parsedSchema: any;
        try {
          parsedSchema = JSON.parse(schema);
        } catch (err) {
          // Schema line isn't valid JSON — the whole `error` payload is a real error.
          throw new Error(response.error);
        }

        const rows: any[] = [];

View on GitHub (pinned to 7d981676b3)

Solutions

1. Increase the timeout: cubeSql(sql, { timeout: 600000 })
2. Optimize the query / use pre-aggregations so it finishes faster
3. Check server health/load if queries that used to be fast now time out

Example fix

// before
const res = await client.cubeSql('SELECT * FROM huge_table');
// after
const res = await client.cubeSql('SELECT * FROM huge_table', { timeout: 10 * 60 * 1000 });

const effectiveTimeoutMs = options?.timeout ?? 5 * 60 * 1000;
if (expectedQueryMs > effectiveTimeoutMs) console.warn('Query likely to exceed cubeSql timeout');

try { const res = await client.cubeSql(sql, { timeout: 600000 }); } catch (e) {
  if (/timed out after \d+ms/.test(e.message)) {
    const res = await withBackoff(() => client.cubeSql(sql, { timeout: 600000 }));
  } else throw e;
}

When it happens

Trigger: cubeSql(sql, { timeout }) where the server/transport exceeds the deadline; no options.timeout means the 5-minute (300000ms) default elapses on a long-running SQL query.

Common situations: Very large CubeSQL queries over slow connections; server-side query taking minutes; too-low custom timeout set by the caller.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

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

Related errors

• connect timeout
• Athena job timeout reached ${this.config.pollTimeout}ms
• HTTP error! status: ${response.status}
• unexpected response ${response.statusText}
• PoolTimeoutError

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