{"record":{"id":"01837b082d0afa2a","repo":"cube-js/cube","slug":"query-param-is-required","errorCode":null,"errorMessage":"Query param is required","messagePattern":"Query param is required","errorType":"validation","errorClass":"UserError","httpStatus":null,"severity":"error","filePath":"packages/cubejs-api-gateway/src/gateway.ts","lineNumber":2445,"sourceCode":"\n  protected resToResultFn(res: ExpressResponse) {\n    return async (message, { status }: { status?: number } = {}) => {\n      if (status) {\n        res.status(status);\n      }\n\n      if (message.isWrapper) {\n        res.set('Content-Type', 'application/json');\n        res.send(Buffer.from(await message.getFinalResult()));\n      } else {\n        res.json(message);\n      }\n    };\n  }\n\n  protected parseQueryParam(query: RequestQuery | 'undefined'): Query | Query[] {\n    if (!query || query === 'undefined') {\n      throw new UserError('Query param is required');\n    }\n\n    if (typeof query === 'string') {\n      try {\n        return JSON.parse(query) as Query | Query[];\n      } catch (e: any) {\n        throw new UserError(`Unable to decode query param as JSON, error: ${e.message}`);\n      }\n    }\n\n    return query as Query | Query[];\n  }\n\n  protected async getCompilerApi(context: RequestContext) {\n    return this.compilerApi(context);\n  }\n\n  protected async getAdapterApi(context: RequestContext) {","sourceCodeStart":2427,"sourceCodeEnd":2463,"githubUrl":"https://github.com/cube-js/cube/blob/7d981676b36392fec34088b9afab6bdcad40207c/packages/cubejs-api-gateway/src/gateway.ts#L2427-L2463","documentation":"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.","triggerScenarios":"GET /cubejs-api/v1/load without a `query` query-string parameter; query= (empty); query=undefined (a client did `${query}` where query was undefined).","commonSituations":"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.","solutions":["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.","Fix URL construction that interpolated an undefined variable — use JSON.stringify(query) and encodeURIComponent.","Use the official @cubejs-client `cubeApi.load(query)` so the parameter is serialized correctly."],"exampleFix":"// before\nfetch(`/cubejs-api/v1/load?query=${query}`); // query may be undefined -> 'undefined'\n// after\nfetch(`/cubejs-api/v1/load?query=${encodeURIComponent(JSON.stringify(query))}`);","handlingStrategy":"validation","validationCode":"const q = JSON.stringify(query);\nif (!query || q === undefined) throw new Error('Refusing request: query param missing');\nconst url = `/cubejs-api/v1/load?query=${encodeURIComponent(q)}`;","typeGuard":"function hasQuery(q: unknown): q is Record<string, unknown> {\n  return typeof q === 'object' && q !== null && Object.keys(q).length > 0;\n}","tryCatchPattern":"try {\n  return await fetch(url, opts);\n} catch (e) {\n  if (String(e?.message).includes('Query param is required')) {\n    console.error('query was undefined/empty when building the URL — check variable assignment');\n    throw e;\n  }\n  throw e;\n}","preventionTips":["Never interpolate raw variables into query strings; always JSON.stringify + encodeURIComponent.","Prefer POST with a JSON body for load requests.","Use the official client's load() so parameter serialization is handled."],"tags":["rest-api","request-validation","http"],"backgroundTag":"missing-required-argument","analyzedSha":"7d981676b36392fec34088b9afab6bdcad40207c","analyzedAt":"2026-09-02T03:45:10.400Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}