refinedev/refine · error · Error

GraphQL operation name required.

Error message

GraphQL operation name required.

What it means

The hasura data provider's custom() method requires a meta object containing an operation name. It throws when meta is provided but meta.operation is missing, because the provider must know which key of the GraphQL response to return. The operation name must match the field/alias in the returned GraphQL payload.

Source

Thrown at packages/hasura/src/dataProvider/index.ts:629

              data: response[meta.operation],
            };
          }
          const { query, variables } = gql.mutation({
            operation: meta.operation,
            fields: meta.fields,
            variables: meta.variables,
          });

          const response = await gqlClient.request<BaseRecord>(
            query,
            variables,
          );

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

export default dataProvider;

View on GitHub (pinned to 779d52a20e)

Solutions

1. Add meta.operation set to the name of the root field returned by your GraphQL query, e.g. { operation: "myQuery", fields, variables }
2. Verify the value matches a top-level key in the response payload so response[meta.operation] resolves
3. Check for typos such as operationName vs operation

Example fix

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

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

const hasOperation = (meta?: any): meta is { operation: string } =>
  !!meta && typeof meta.operation === "string" && meta.operation.length > 0;
if (!hasOperation(meta)) throw new Error("custom() requires meta.operation");

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")) { /* fix meta.operation and retry */ } else throw e; }

When it happens

Trigger: Calling resources.custom({ url, method, meta: { fields, variables } }) without meta.operation, or with a typo'd key like meta.operationName. Happens when the meta object lacks the operation property while fields/variables exist.

Common situations: Migrating custom() calls from another provider where meta only carried query variables; typos in meta keys; assuming the provider infers the operation from the query string.

Related errors

• GraphQL need to operation, fields and variables values in me
• GraphQL operation name required.
• @packages/hasura: multiple filters present. Group multiple p
• GraphQL does not support ${method} method.
• GraphQL needs operation, fields and variables values in meta

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