cube-js/cube · error

Variable "${value.name.value}" is not defined

Error message

Variable "${value.name.value}" is not defined

What it means

When translating a GraphQL query into a Cube query, parseArgumentValue resolves `Variable`-kind argument nodes against the supplied variables object. If a variable is referenced but not present (or present as undefined) in that map, this Error is thrown naming the variable.

Source

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

function parseArgumentValue(value: ValueNode, variables?: Record<string, any>) {
  switch (value.kind) {
    case 'BooleanValue':
    case 'IntValue':
    case 'StringValue':
    case 'FloatValue':
    case 'EnumValue':
      return value.value;
    case 'ListValue':
      return value.values.map(v => parseArgumentValue(v, variables));
    case 'ObjectValue':
      return value.fields.reduce((obj, v) => ({
        ...obj,
        [v.name.value]: parseArgumentValue(v.value, variables),
      }), {});
    case 'Variable':
      if (variables?.[value.name.value] === undefined) {
        throw new Error(`Variable "${value.name.value}" is not defined`);
      }

      return variables[value.name.value];
    default:
      return undefined;
  }
}

function getArgumentValue(node: FieldNode, argName: string, variables: Record<string, any> = {}) {
  const argument = node.arguments?.find(a => a.name.value === argName)?.value;

  if (argument?.kind === 'Variable') {
    const varValue = variables[argument.name.value];
    if (varValue === undefined) {
      throw new Error(`Variable "${argument.name.value}" is not defined`);
    }
    return variables[argument.name.value];
  }

View on GitHub (pinned to 7d981676b3)

Solutions

1. Pass every variable referenced in the GraphQL document in the variables object with defined values.
2. Fix key-name typos so variable names in the query match the variables record exactly.
3. Substitute concrete values instead of variables for optional fields, or omit the argument when the value is absent.
4. Validate variables before calling: assert each declared variable has a defined value.

Example fix

// before
getJsonQueryFromGraphQLQuery(doc, {}); // query uses $dateRange
// after
getJsonQueryFromGraphQLQuery(doc, { dateRange: ['2024-01-01', '2024-01-31'] });

function assertVariablesDefined(doc, variables = {}) {
  const used = new Set();
  doc.definitions.forEach(d => (d.selectionSet?.selections || []).forEach(s =>
    (s.arguments || []).forEach(a => { if (a.value?.kind === 'Variable') used.add(a.value.name.value); })));
  const missing = [...used].filter(name => variables[name] === undefined);
  if (missing.length) throw new Error(`Missing variables: ${missing.join(', ')}`);
}

function hasAllVariables(variables, requiredNames) {
  return requiredNames.every(n => variables?.[n] !== undefined);
}

try {
  const cubeQuery = getJsonQueryFromGraphQLQuery(doc, variables);
} catch (e) {
  if (/is not defined/.test(e.message)) {
    // supply the named variable from the message before re-running
  }
  throw e;
}

When it happens

Trigger: Calling getJsonQueryFromGraphQLQuery with a GraphQL document using `$var` in arguments but passing a variables record missing that key — or the key defined with an undefined value, e.g. variables: { dateRange: undefined }.

Common situations: Typos between the declared variable name in the query and the variables object key; forgetting to pass the variables argument entirely; constructing queries dynamically where a variable is only sometimes populated.

Related errors

• Variable "${argument.name.value}" is not defined
• A user-defined contextToApiScopes function returns a wrong s
• 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/34c51c8c72406c73. Report an issue: GitHub.