cube-js/cube · error

query parameter must be a non-empty string

Error message

query parameter must be a non-empty string

What it means

The /v1/convert endpoint requires `query` to be a non-empty, non-whitespace string containing the SQL to convert. convertQuery validates `typeof payload.query === 'string' && payload.query.trim()` and throws otherwise. Missing, null, numeric, or whitespace-only query values all trigger this error.

Source

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

      },
      requestId: context.requestId
    };
  }

  protected async convertQuery({ payload, context, res }: QueryConvertRequest) {
    try {
      await this.assertApiScope('sql', context.securityContext);

      if (payload.input !== 'sql') {
        throw new Error(`Unexpected input parameter value '${payload.input}'`);
      }

      if (payload.output !== 'rest') {
        throw new Error(`Unexpected output parameter value '${payload.output}'`);
      }

      if (typeof payload.query !== 'string' || !payload.query.trim()) {
        throw new Error('query parameter must be a non-empty string');
      }

      const result = await this.sqlServer.rest4sql(payload.query, context.securityContext);

      await res(result);
    } catch (e: any) {
      this.handleError({
        e,
        context,
        query: payload,
        res,
      });
    }
  }

  protected async dryRun({ query, context, res }: QueryRequest) {
    const requestStarted = new Date();

View on GitHub (pinned to 7d981676b3)

Solutions

1. Ensure `query` is a non-empty string containing the SQL, e.g. query: 'SELECT ...'.
2. Validate in the client before sending: typeof query === 'string' && query.trim().length > 0.
3. If the query comes from user input, trim it and refuse to submit the request until it is populated.

Example fix

// before
const body = { input: 'sql', output: 'rest', query: sqlEditor.value ?? undefined };
// after
const sql = (sqlEditor.value ?? '').trim();
if (!sql) throw new Error('SQL is required before converting');
const body = { input: 'sql', output: 'rest', query: sql };

if (typeof body.query !== 'string' || !body.query.trim()) throw new Error('A non-empty SQL string is required for /v1/convert');

function isNonEmptyString(v: unknown): v is string { return typeof v === 'string' && v.trim().length > 0; }

try {
  return await convertEndpoint(body);
} catch (e) {
  if (String(e?.message).includes('query parameter must be a non-empty string')) {
    throw new Error('Provide SQL in the query field before converting');
  }
  throw e;
}

When it happens

Trigger: POST /cubejs-api/v1/convert with query omitted, null, undefined, a number/object instead of a string, or a string containing only spaces/newlines.

Common situations: Forgetting to pass the SQL text when building the request dynamically; JSON serialization dropping an undefined query field; a UI sending the request before the SQL editor has content.

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

• Unexpected input parameter value '${payload.input}'
• Unexpected output parameter value '${payload.output}'
• Can't parse date: '${from}'
• Can't parse date: '${to}'
• Can't parse date: '${dateString}'

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