refinedev/refine · error · Error

GraphQL operation name required.

Error message

GraphQL operation name required.

What it means

The nestjs-query data provider's custom() method requires meta.operation naming the GraphQL operation whose result should be returned. It throws when meta exists but has no operation key, since the provider returns response[meta.operation] from the GraphQL payload.

Source

Thrown at packages/nestjs-query/src/dataProvider/index.ts:491

              operation: meta.operation,
              fields: meta.fields,
              variables: meta.variables,
            });

            query = gqlMutation.query;
            variables = gqlMutation.variables;
          }

          const response = await _client.request<BaseRecord>({
            document: query,
            variables,
          });

          return {
            data: response[meta.operation],
          };
        }
        throw Error("GraphQL operation name required.");
      }
      throw Error(
        "GraphQL needs operation, fields and variables values in meta object.",
      );
    },
  };
};

export default dataProvider;

View on GitHub (pinned to 779d52a20e)

Solutions

1. Add meta.operation matching the root field of your GraphQL query/mutation
2. Make sure the name is a top-level key of the parsed response
3. Double-check spelling: operation, fields, variables are the expected keys

Example fix

// before
await dataProvider.custom({ url: "", method: "post", meta: { fields: ["id"], variables: {} } });

// after
await dataProvider.custom({ url: "", method: "post", meta: { operation: "user", fields: ["id", "email"], variables: { id: 1 } } });

if (!meta || typeof meta.operation !== "string") throw new Error("meta.operation required");

const isCustomMeta = (m: unknown): m is { operation: string; fields: any[]; variables: Record<string, unknown> } =>
  typeof m === "object" && m !== null && "operation" in m && "fields" in m && "variables" in m;

try { await dataProvider.custom({ url, method, meta }); } catch (e) { if (String(e).includes("operation name required")) { /* add meta.operation */ } else throw e; }

When it happens

Trigger: Calling custom({ url, method, meta }) where meta lacks operation (e.g. only fields and variables are supplied), or misspelling the key.

Common situations: Reusing meta shapes from other providers; assuming the operation is inferred from the query document; key typos like operationName.

Related errors

• GraphQL operation name required.
• GraphQL does not support ${method} method.
• GraphQL needs operation, fields and variables values in meta
• GraphQL need to operation, fields and variables values in me
• [Code] Operation is required.

AI-assisted analysis of refinedev/refine@779d52a20e (2026-08-27). Data as JSON: /api/errors/164e2a082b373483. Report an issue: GitHub.