Fusion does not propagate subgraphs request-level errors to the gateway response

[moeb-trackman]

Product

Hot Chocolate

Version

16.1.0-p.1.11

Link to minimal reproduction

https://github.com/moeb-trackman/HotChocolate-Fusion-Bug/

Steps to reproduce

Return an request-level error within a resolver in a subgraph

context.ReportError("This is an error message from the resolver.");

Running the query against subgraph returns the request-level error but gateway does not.

What is expected?

Gateway must propagate the request-level error of subgraphs to the response

{
 "errors": [
    {
      "message": "This is an error message from the resolver.",
      "path": [
        "orders"
      ]
    }
  ]
  "data": {}
}

What is actually happening?

{
  "data": {}
  # NO ERROR !
}

Relevant log output

Additional context

No response

[tobias-tengler]

I think the issue is that you are still returning data alongside the error (your orders field returns an empty array instead of null). This is not allowed per the spec:

https://spec.graphql.org/draft/#sec-Errors.Execution-Errors

Could you try returning null from the resolver? Is the error included then?
EDIT: Confirmed this is the cause.

[tobias-tengler]

Can you update your subgraph code to throw a GraphQLException instead? This would be the proper way.
I'm discussing with the team right now if we can deprecate the ReportError API as it allows you to produce these invalid results.

Updating the gateway would mean having to check for errors for each successful field, which I'd like to avoid.

[moeb-trackman]

Thanks, I updated the code, and yes, once the field resolves to null, Fusion correctly propagates the error.

But a few things:

1- This is a breaking change since the behaviour is changed (even correctly according to spec)
Even if the previous behavior was technically spec-invalid, many existing applications may already depend on it in practice.

2- In our case, we intentionally use request-level errors together with partial/non-null data.
Our frontend and downstream clients rely on this pattern heavily. Migrating everything to either (throwing GraphQLException or force returning null) would require significant refactoring across multiple services and consumers.

3- I would expect this validation/enforcement to happen at the GraphQL server layer, not at the Fusion gateway layer.
If returning execution errors alongside non-null data is considered invalid per the GraphQL spec, then ideally the subgraph server (e.g. HotChocolate.AspNetCore) should normalize or reject such responses before they ever reach Fusion.

So given our situations what should we do?
Having a compatibility switch can solve this compatibility regression.

[michaelstaib]

Hey @moeb-trackman,

3 - Correct, Hot Chocolate should reject that. The reason it does not is legacy code. We will deprecate this with HC 16.1.

1 - Version 16 is a major version, and Fusion is a rewrite on top of the 2025 GraphQL specification. We will make sure to call this out in our migration guide. Unfortunately, a change here is not possible. That said, we are still supporting Hot Chocolate Fusion 15 for a while, so there is no rush to migrate.

2 - This is really because we misinterpreted the older GraphQL spec text. The single field error rule is important and has major implications from client to server.

Also, the gateway is a fully valid GraphQL server, so we cannot just wire data through. Within the gateway we need to do all the things we do in standard GraphQL servers, like error propagation for instance. The impact of adding non-spec-compliant fallback behavior would cause ripple effects across the gateway in the hot path, which is unfeasible.

What might be an easy fix is to have a warnings list on the extensions map of the request, which would be the errors per field. In Fusion 16 you could do a preprocess and move errors for non-null fields to extensions automatically, then add a post-processor on the result that shifts it back into errors. If you want to do that, we can help you achieve this. This would allow your old behavior.

[moeb-trackman]

Thanks @michaelstaib

I implemented your suggestion with some tweaks and it's working well.

• A http DelegatingHandler that captures errors field when data is not null and stores it HttpContext.Items
• A RequestMiddleware that restores captured errors into the final response as errors field

Sharing it here in case it might be helpful for others as well. Also curious to hear what you think about it.

var builder = WebApplication.CreateBuilder(args);

builder.Services
    .AddCaptureRequestError() // <------ Add a DelegatingHandler to capture subgraph errors with non-null data
    .AddHttpClient("fusion");

builder
    .AddGraphQLGateway()
    .AddFileSystemConfiguration("./gateway.far")
    .UseRestoreRequestError(); // <------ Add a request middleware to restore captured errors into the final response

var app = builder.Build();

app.MapGraphQL();

await app.RunAsync();

public static class RequestErrorHandlingExtensions
{
    public static IServiceCollection AddCaptureRequestError(this IServiceCollection services)
    {
        ArgumentNullException.ThrowIfNull(services);

        services.AddHttpContextAccessor();
        services.AddTransient<CaptureRequestErrorHandler>();

        // Attach the handler to every subgraph HttpClient.
        // Fusion uses named IHttpClientFactory clients per subgraph, so ConfigureAll
        // is the simplest way to cover all of them without naming each.
        return services.ConfigureAll<HttpClientFactoryOptions>(opts =>
        {
            opts.HttpMessageHandlerBuilderActions.Add(b =>
            {
                var handler = b.Services.GetRequiredService<CaptureRequestErrorHandler>();
                b.AdditionalHandlers.Add(handler);
            });
        });
    }

    public static IFusionGatewayBuilder UseRestoreRequestError(this IFusionGatewayBuilder builder)
    {
        ArgumentNullException.ThrowIfNull(builder);

        return builder.UseRequest(RestoreRequestErrorMiddleware.Create());
    }
}

public sealed class CaptureRequestErrorHandler(
    IHttpContextAccessor httpContextAccessor,
    ILogger<CaptureRequestErrorHandler> logger) : DelegatingHandler
{
    public const string HttpContextKey = "__GraphQL_RequestErrors";

    private static readonly HashSet<string> JsonMediaTypes = new(StringComparer.OrdinalIgnoreCase)
    {
        "application/json",
        "application/graphql-response+json",
        "application/graphql+json"
    };

    protected override async Task<HttpResponseMessage> SendAsync(
        HttpRequestMessage request,
        CancellationToken cancellationToken)
    {
        var response = await base.SendAsync(request, cancellationToken).ConfigureAwait(false);

        if (!response.IsSuccessStatusCode || response.Content is null)
            return response;

        // Skip subscriptions (text/event-stream), multipart/defer, etc.
        var mediaType = response.Content.Headers.ContentType?.MediaType;
        if (mediaType is null || !JsonMediaTypes.Contains(mediaType))
            return response;

        byte[] body;
        try
        {
            body = await response.Content.ReadAsByteArrayAsync(cancellationToken).ConfigureAwait(false);
        }
        catch (Exception ex)
        {
            logger.LogError(ex, "Failed to read subgraph response body to capture request errors.");
            throw; //return response;
        }

        if (body.Length == 0)
            return response;

        try
        {
            using var doc = JsonDocument.Parse(body);
            var root = doc.RootElement;

            if (root.ValueKind != JsonValueKind.Object)
                return response;

            // Need both errors AND non-null data for this to be the case we care about.
            if (!root.TryGetProperty("errors", out var errors)
                || errors.ValueKind != JsonValueKind.Array
                || errors.GetArrayLength() == 0)
            {
                return response;
            }

            var dataIsNullOrMissing =
                !root.TryGetProperty("data", out var data)
                || data.ValueKind == JsonValueKind.Null;

            // If data is null, Fusion already propagates errors → don't touch.
            if (dataIsNullOrMissing)
                return response;

            // Capture (clone — the JsonDocument disposes when we leave this scope).
            var httpContext = httpContextAccessor.HttpContext;
            if (httpContext is not null)
            {
                var captured = httpContext.Items[HttpContextKey] as List<JsonElement> ?? [];

                foreach (var error in errors.EnumerateArray())
                    captured.Add(error.Clone());

                httpContext.Items[HttpContextKey] = captured;
            }
        }
        catch (JsonException ex)
        {
            logger.LogDebug(ex, "Subgraph response was not JSON; leaving as-is.");
        }

        return response;
    }
}


public sealed class RestoreRequestErrorMiddleware(
    HotChocolate.Execution.RequestDelegate next,
    IHttpContextAccessor? httpContextAccessor)
{
    public static RequestMiddlewareConfiguration Create()
    {
        return new RequestMiddlewareConfiguration((factoryContext, next) =>
        {
            var middleware = new RestoreRequestErrorMiddleware(next,
                factoryContext.Services.GetService<IHttpContextAccessor>());
            return context => middleware.InvokeAsync(context);
        });
    }
    
    public async ValueTask InvokeAsync(RequestContext context)
    {
        await next(context).ConfigureAwait(false);

        var httpContext = httpContextAccessor?.HttpContext;
        if (httpContext is null) return;

        if (httpContext.Items[CaptureRequestErrorHandler.HttpContextKey]
            is not List<JsonElement> { Count: > 0 } captured)
        {
            return;
        }

        // Subscriptions / @defer / @stream produce a response stream — leave those alone.
        if (context.Result is not OperationResult operationResult) 
            return;

        var errors = captured.ConvertAll(ConvertToError);
        operationResult.Errors = operationResult.Errors.AddRange(errors);
    }

    private static IError ConvertToError(JsonElement json)
    {
        var builder = ErrorBuilder.New();

        if (json.TryGetProperty("message", out var msg) && msg.ValueKind == JsonValueKind.String
            && msg.GetString() is string message)
        {
            builder.SetMessage(message);
        }

        if (json.TryGetProperty("path", out var path) && path.ValueKind == JsonValueKind.Array)
        {
            var segments = new List<object>();
            foreach (var seg in path.EnumerateArray())
            {
                segments.Add(seg.ValueKind switch
                {
                    JsonValueKind.String => seg.GetString()!,
                    JsonValueKind.Number => seg.GetInt32(),
                    _ => seg.GetRawText()
                });
            }
            builder.SetPath(HotChocolate.Path.FromList(segments));
        }

        if (json.TryGetProperty("locations", out var locs) && locs.ValueKind == JsonValueKind.Array)
        {
            foreach (var loc in locs.EnumerateArray())
            {
                if (loc.TryGetProperty("line", out var l)
                    && loc.TryGetProperty("column", out var c))
                {
                    builder.AddLocation(new Location(l.GetInt32(), c.GetInt32()));
                }
            }
        }

        if (json.TryGetProperty("extensions", out var ext) && ext.ValueKind == JsonValueKind.Object)
        {
            foreach (var prop in ext.EnumerateObject())
                builder.SetExtension(prop.Name, JsonElementToObject(prop.Value));
        }

        return builder.Build();
    }

    private static object? JsonElementToObject(JsonElement el)
    {
        return el.ValueKind switch
        {
            JsonValueKind.String => el.GetString(),
            JsonValueKind.Number => el.TryGetInt64(out var i) ? i : el.GetDouble(),
            JsonValueKind.True => true,
            JsonValueKind.False => false,
            JsonValueKind.Null => null,
            JsonValueKind.Object => el.EnumerateObject().ToDictionary(p => p.Name, p => JsonElementToObject(p.Value)),
            JsonValueKind.Array => el.EnumerateArray().Select(JsonElementToObject).ToList(),
            _ => el.GetRawText()
        };
    }
}