OrchardCMS/OrchardCore · error · InvalidOperationException

The 'query' query string parameter is missing

Error message

The 'query' query string parameter is missing

What it means

For GET requests (and non-JSON POSTs) GraphQLMiddleware reads the GraphQL query from the 'query' query string parameter. When it is absent and validation is enabled, CreateRequestFromQueryString throws this InvalidOperationException, surfaced to the client as a GraphQL processing error.

Solutions

  1. Append the query parameter: GET /api/graphql?query={ me { id } } (URL-encoded).
  2. Double-check the parameter is exactly 'query' (lowercase) and correctly URL-encoded.
  3. For persistent queries, register an INamedQueryProvider and pass ?query= via the named entry, or move to a POST JSON body.
  4. Switch to POST with a JSON body when the query is large (avoids URL length limits).

Example fix

// before
fetch('/api/graphql?variables={}')
// after
fetch('/api/graphql?query=' + encodeURIComponent('{ me { id } }'))
Defensive patterns

Strategy: validation

Validate before calling

const url = '/api/graphql?query=' + encodeURIComponent(query);
if (!query || !query.trim()) throw new Error('GraphQL query is required');

Try / catch

const res = await fetch(url);
const result = await res.json();
if (result.errors?.some(e => e.message.includes("'query' query string parameter is missing"))) {
    // reconstruct URL with the encoded query parameter
}

Prevention

When it happens

Trigger: GET /OrchardCore.Apis.GraphQL endpoint without ?query=..., or a POST with an unsupported content type and no ?query= query string parameter.

Common situations: Calling the endpoint with only variables or operationName in the URL, bookmarked/partially constructed URLs, clients omitting the query while intending a named query that doesn't exist.

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

AI-assisted analysis of OrchardCMS/OrchardCore@4306c0717f (2026-09-13). Data as JSON: /api/errors/44c8128252a61447. Report an issue: GitHub.

Appendix: source

Thrown at src/OrchardCore.Modules/OrchardCore.Apis.GraphQL/GraphQLMiddleware.cs:191

        context.Response.StatusCode = (int)(result.Errors == null || result.Errors.Count == 0
            ? HttpStatusCode.OK
            : result.Errors.Any(x => x is ValidationError ve && ve.Number == RequiresPermissionValidationRule.ErrorCode)
                ? HttpStatusCode.Unauthorized
                : HttpStatusCode.BadRequest);

        context.Response.ContentType = MediaTypeNames.Application.Json;

        await _serializer.WriteAsync(context.Response.Body, result);
    }

    private GraphQLNamedQueryRequest CreateRequestFromQueryString(HttpContext context, bool validateQueryKey = false)
    {
        if (!context.Request.Query.ContainsKey("query"))
        {
            if (validateQueryKey)
            {
                throw new InvalidOperationException("The 'query' query string parameter is missing");
            }

            return null;
        }

        var request = new GraphQLNamedQueryRequest
        {
            Query = context.Request.Query["query"],
        };

        if (context.Request.Query.ContainsKey("variables"))
        {
            request.Variables = _graphQLTextSerializer.Deserialize<Inputs>(context.Request.Query["variables"]);
        }

        if (context.Request.Query.ContainsKey("operationName"))
        {
            request.OperationName = context.Request.Query["operationName"];

View on GitHub (pinned to 4306c0717f)