cube-js/cube · error · UserError

Query param is required

Error message

Query param is required

What it means

The REST /load endpoint expects the query to be supplied in the `query` request parameter (JSON-encoded for GET requests). parseQueryParam throws this UserError when the query param is missing, empty, or literally the string 'undefined' — the latter being a common artifact of JavaScript string-interpolating an undefined variable into a URL.

Source

Thrown at packages/cubejs-api-gateway/src/gateway.ts:2445

  protected resToResultFn(res: ExpressResponse) {
    return async (message, { status }: { status?: number } = {}) => {
      if (status) {
        res.status(status);
      }

      if (message.isWrapper) {
        res.set('Content-Type', 'application/json');
        res.send(Buffer.from(await message.getFinalResult()));
      } else {
        res.json(message);
      }
    };
  }

  protected parseQueryParam(query: RequestQuery | 'undefined'): Query | Query[] {
    if (!query || query === 'undefined') {
      throw new UserError('Query param is required');
    }

    if (typeof query === 'string') {
      try {
        return JSON.parse(query) as Query | Query[];
      } catch (e: any) {
        throw new UserError(`Unable to decode query param as JSON, error: ${e.message}`);
      }
    }

    return query as Query | Query[];
  }

  protected async getCompilerApi(context: RequestContext) {
    return this.compilerApi(context);
  }

  protected async getAdapterApi(context: RequestContext) {

View on GitHub (pinned to 7d981676b3)

Solutions

1. Include a JSON-encoded query in the request: GET /cubejs-api/v1/load?query=%7B%22measures%22%3A%5B...%5D%7D or send it as the JSON body of a POST.
2. Fix URL construction that interpolated an undefined variable — use JSON.stringify(query) and encodeURIComponent.
3. Use the official @cubejs-client `cubeApi.load(query)` so the parameter is serialized correctly.

Example fix

// before
fetch(`/cubejs-api/v1/load?query=${query}`); // query may be undefined -> 'undefined'
// after
fetch(`/cubejs-api/v1/load?query=${encodeURIComponent(JSON.stringify(query))}`);

const q = JSON.stringify(query);
if (!query || q === undefined) throw new Error('Refusing request: query param missing');
const url = `/cubejs-api/v1/load?query=${encodeURIComponent(q)}`;

function hasQuery(q: unknown): q is Record<string, unknown> {
  return typeof q === 'object' && q !== null && Object.keys(q).length > 0;
}

try {
  return await fetch(url, opts);
} catch (e) {
  if (String(e?.message).includes('Query param is required')) {
    console.error('query was undefined/empty when building the URL — check variable assignment');
    throw e;
  }
  throw e;
}

When it happens

Trigger: GET /cubejs-api/v1/load without a `query` query-string parameter; query= (empty); query=undefined (a client did `${query}` where query was undefined).

Common situations: Template-literal URL building where the query variable was never assigned; stripping the query string during a redirect; curl/httpie tests omitting the --data-urlencode for query.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Invalid query format: ${error.message || error.toString()}
• No job description provided
• Unable to decode query param as JSON, error: ${e.message}
• Can't parse date: '${from}'
• Can't parse date: '${to}'

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