cube-js/cube · error · UserError

Invalid query format: ${error.message || error.toString()}

Error message

Invalid query format: ${error.message || error.toString()}

What it means

Input validation in normalizeQuery: the submitted query object failed Joi validation against querySchema. It fires for any malformed query field — wrong types (e.g. measures as string instead of array), unknown keys, or invalid values — before any further normalization occurs.

Source

Thrown at packages/cubejs-api-gateway/src/query.js:440

  query.cache = undefined;

  return query;
}

/**
 * Normalize incoming network query.
 * @param {Query} query
 * @param {boolean} persistent
 * @param {CacheMode} [cacheMode]
 * @throws {UserError}
 * @returns {import('./types/query').NormalizedQuery}
 */
const normalizeQuery = (query, persistent, cacheMode) => {
  query = normalizeQueryCacheMode(query, cacheMode);
  query.timezone = query.timezone || getEnv('defaultTimezone');
  const { error, value } = querySchema.validate(query);
  if (error) {
    throw new UserError(`Invalid query format: ${error.message || error.toString()}`);
  }

  const validQuery = query.measures?.length ||
    query.dimensions?.length ||
    query.timeDimensions?.filter(td => !!td.granularity).length;
  if (!validQuery) {
    throw new UserError(
      'Query should contain either measures, dimensions or timeDimensions with granularities in order to be valid'
    );
  }

  const regularToTimeDimension = (query.dimensions || []).filter(d => typeof d === 'string' && d.split('.').length === 3).map(d => ({
    dimension: d.split('.').slice(0, 2).join('.'),
    granularity: d.split('.')[2]
  }));
  const timezone = value.timezone || 'UTC';

  const def = getEnv('dbQueryDefaultLimit') <= getEnv('dbQueryLimit')

View on GitHub (pinned to 7d981676b3)

Solutions

1. Read the Joi error message embedded in the error; it pinpoints the offending query key and expected type.
2. Ensure measures, dimensions, and timeDimensions are arrays of strings/objects as documented.
3. Remove unknown properties from the query object; the schema rejects unexpected keys.

When it happens

Trigger: Thrown at packages/cubejs-api-gateway/src/query.js:440 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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