[graphql-pro] @defer incremental delivery: wrong path when sibling fields exist at same level (GraphQL::Pro::Defer)

[robinvrd]

Note: this involves GraphQL::Pro::Defer — happy to follow up through pro support channels if preferred.

---

Describe the bug

When a query uses @defer on a field and a sibling field exists at the same parent level (e.g. mcpServers alongside environment), the incremental delivery chunks contain the wrong path. The deferred data is delivered with the path of a sibling's node instead of the correct path, causing clients to apply the patch to the wrong location.

Versions

graphql version: 2.5.13
graphql-pro version: 1.29.13
rails: 8.0.4.1

GraphQL schema

class ApplicationSchema < GraphQL::Schema
  use GraphQL::Pro::Defer
  use GraphQL::Pro::FutureStream
end

# Controller
class GraphQLController < ApplicationController
  include ActionController::Live

  def execute
    result = ApplicationSchema.execute(query, variables:, context:, operation_name:)
    (deferred = result.context[:defer]) ? render_stream(deferred) : render(json: result)
  end

  def render_stream(deferred)
    response.headers['Last-Modified'] = Time.now.httpdate
    deferred.stream_http_multipart(response, incremental: true)
  end
end

# Relevant types (simplified)
class OrganizationType < GraphQL::Schema::Object
  field :environment, EnvironmentType, null: true
  field :mcp_servers, MCPServerType.connection_type, null: false
end

class EnvironmentType < GraphQL::Schema::Object
  field :connections, ConnectionType.connection_type, null: false
end

class ConnectionType < GraphQL::Schema::Object
  field :connected, Boolean, null: false
end

class MCPServerType < GraphQL::Schema::Object
  field :task_counts, TaskStatusCountsType, null: false
end

GraphQL query

query ConnectionsQuery($organizationId: ID!, $environmentSlug: String!) {
  organization(id: $organizationId) {
    id
    environment(slug: $environmentSlug) {
      id
      connections(first: 10) {
        nodes {
          id
          ... @defer {
            connected
          }
        }
      }
    }
    mcpServers(first: 10) {
      nodes {
        id
        taskCounts {
          total
        }
      }
    }
  }
}

Steps to reproduce

1. Set up a schema with use GraphQL::Pro::Defer and a controller using stream_http_multipart(response, incremental: true)
2. Define a query type with two sibling fields at the same level — one containing a @defer fragment, the other with regular nested fields
3. Execute the query and inspect the raw multipart HTTP response chunks

Expected behavior

Incremental chunks should carry the correct path pointing to the deferred selection set inside environment.connections.nodes:

{ "incremental": [{ "path": ["organization", "environment", "connections", "nodes", 0], "data": { "connected": true } }], "hasNext": true }
{ "incremental": [{ "path": ["organization", "environment", "connections", "nodes", 1], "data": { "connected": true } }], "hasNext": false }

Actual behavior

Both incremental chunks carry a path pointing to the sibling field (mcpServers) instead of environment.connections, and both incorrectly use index 0:

Chunk 1 (initial) — correct:

{
  "hasNext": true,
  "data": {
    "organization": {
      "environment": {
        "connections": { "nodes": [{ "id": "aca6e0bf-..." }, { "id": "ed1b3e5e-..." }] }
      },
      "mcpServers": {
        "nodes": [{ "id": "019c4c22-...", "taskCounts": { "total": 0 } }]
      }
    }
  }
}

Chunk 2 — ❌ wrong path, wrong field, wrong index:

{ "incremental": [{ "path": ["organization", "mcpServers", "nodes", 0, "__typename"], "data": { "connected": true } }], "hasNext": true }

Chunk 3 — ❌ wrong path, wrong field, same index 0 for both items:

{ "incremental": [{ "path": ["organization", "mcpServers", "nodes", 0, "__typename"], "data": { "connected": true } }], "hasNext": false }

Two distinct issues in the paths:

1. Wrong field: points to mcpServers instead of environment.connections
2. Wrong index: both chunks use index 0 instead of 0 and 1

Additional context

• Removing taskCounts from mcpServers (or removing mcpServers entirely) produces correct paths — the bug only manifests when a sibling field with nested selections exists alongside the @defer-containing field at the same parent level.
• The query validates fine; the schema is otherwise functioning correctly.
• Workaround: remove @defer from the query or split into two separate queries.

[rmosolgo]

Hey, thanks for the detailed report and sorry about the trouble with this. This is a really weird case ...I can't think of any reason on the top of my head why that sibling field would make this mixed up, but there it is! I'll dig in tomorrow morning and report back with what I find.

In the meantime, I noticed that __typename turned up in the (wrong) "path": ... entries in Chunk 2 and Chunk 3. If you check the Rails servers, do you see __typename in the GraphQL query that Rails received? I'm wondering where that came from -- client libraries often insert it during a preprocessing step. I'd be surprised if GraphQL-Ruby stuck it in there from nowhere 😖

[robinvrd]

About __typename, I might have cleaned them from here for clarity, but they were in the query orignally, on me!

[rmosolgo]

Ok, interesting -- were they inside the nodes { ... } selection (as a sibling to id), or inside the ... @defer { ... } fragment ) (as a sibling to connected)? Or both, or somewhere else?

I've been working up a replication script for this bug, but the simplest case works as expected:

@defer sibling list bug

require "bundler/inline"

gemfile(true) do
  gem "graphql", "2.5.13"
  gem "graphql-pro", "1.29.13", source: "https://gems.graphql.pro"
  gem "ostruct"
end

class ExampleSchema < GraphQL::Schema
  class TaskCountType < GraphQL::Schema::Object
    field :total, Integer
  end

  class MCPServerType < GraphQL::Schema::Object
    field :id, ID
    field :task_counts, TaskCountType, null: false
  end


  class ConnectionType < GraphQL::Schema::Object
    field :id, ID
    field :connected, Boolean, null: false
  end

  class EnvironmentType < GraphQL::Schema::Object
    field :id, ID
    field :connections, ConnectionType.connection_type, null: false
  end

  class OrganizationType < GraphQL::Schema::Object
    field :id, ID
    field :environment, EnvironmentType do
      argument :slug, String
    end

    def environment(slug:)
      object.environment
    end

    field :mcp_servers, MCPServerType.connection_type, null: false
  end

  class Query < GraphQL::Schema::Object
    field :organization, OrganizationType do
      argument :id, ID
    end

    def organization(id:)
      OpenStruct.new(
        id: "8",
        environment: OpenStruct.new(
          id: "7",
          connections: [
            OpenStruct.new(id: "4", connected: true),
            OpenStruct.new(id: "5", connected: true),
            OpenStruct.new(id: "6", connected: false)
          ]
        ),
        mcp_servers: [
          OpenStruct.new(id: "1", task_counts: OpenStruct.new(total: 3)),
          OpenStruct.new(id: "2", task_counts: OpenStruct.new(total: 4)),
          OpenStruct.new(id: "3", task_counts: OpenStruct.new(total: 5)),
        ]
      )
    end
  end

  query(Query)
  use GraphQL::Pro::Defer
end


query_str = <<~GRAPHQL
query ConnectionsQuery($organizationId: ID!, $environmentSlug: String!) {
  organization(id: $organizationId) {
    id
    environment(slug: $environmentSlug) {
      id
      connections(first: 10) {
        nodes {
          id
          ... @defer {
            connected
          }
        }
      }
    }
    mcpServers(first: 10) {
      nodes {
        id
        taskCounts {
          total
        }
      }
    }
  }
}
GRAPHQL


result = ExampleSchema.execute(query_str, variables: { organizationId: "5", environmentSlug: "ABC" })
result.context[:defer].each.with_index do |d, idx|
  puts "\nPatch #{idx + 1}\n"
  pp d.to_incremental_h
end

# Patch 1
#
# {incremental:
#   [{path: nil,
#     data:
#      {"organization" =>
#        {"id" => "8",
#         "environment" => {"id" => "7", "connections" => {"nodes" => [{"id" => "4"}, {"id" => "5"}, {"id" => "6"}]}},
#         "mcpServers" =>
#          {"nodes" =>
#            [{"id" => "1", "taskCounts" => {"total" => 3}},
#             {"id" => "2", "taskCounts" => {"total" => 4}},
#             {"id" => "3", "taskCounts" => {"total" => 5}}]}}}}],
#  hasNext: true}
#
# Patch 2
#
# {incremental: [{path: ["organization", "environment", "connections", "nodes", 0], data: {"connected" => true}}], hasNext: true}
#
# Patch 3
#
# {incremental: [{path: ["organization", "environment", "connections", "nodes", 1], data: {"connected" => true}}], hasNext: true}
#
# Patch 4
#
# {incremental: [{path: ["organization", "environment", "connections", "nodes", 2], data: {"connected" => false}}], hasNext: false}

So I'm obviously missing something....

It'd be good to figure out where __typename fits into the example.

Also, are any of these fields using Dataloader (or GraphQL::Batch)? Maybe batch loading is involved here.

In the meantime, I'll take a look thorugh the source to see if I can find any clues.

[robinvrd]

Thanks for the quick follow-up! A few clarifications:

On __typename

We stripped them when simplifying the query for the issue — apologies for the confusion. In the original query, __typename was in both places:

query ConnectionsQuery($organizationId: ID!, $environmentSlug: String!) {
  organization(id: $organizationId) {
    id
    environment(slug: $environmentSlug) {
      id
      connections(first: 10) {
        nodes {
          id
          ... @defer {
            id
            connected
            __typename
          }
          __typename
        }
        __typename
      }
      __typename
    }
    mcpServers(first: 10) {
      nodes {
        id
        taskCounts {
          total
          __typename
        }
        __typename
      }
      __typename
    }
    __typename
  }
}

Worth noting: the wrong path in the actual response ends with __typename — ["organization", "mcpServers", "nodes", 0, "__typename"] — which suggests the __typename inside the @defer block may be the key trigger.

On Dataloader

Yes, taskCounts uses GraphQL::Dataloader. The resolver calls dataloader.with(AssociationLoader, MCPServer, :tasks).load(object) to batch-load the :tasks association. Removing taskCounts from mcpServers (so no dataloader is involved) makes the paths come out correctly.

[rmosolgo]

Thanks for that context -- I've got it failing locally now! I'll work up a fix and follow up here soon.

[rmosolgo]

I worked up a fix in #5597. Could you give that branch a try locally and confirm it fixes your app?

gem "graphql", github: "rmosolgo/graphql-ruby", ref: "list-dataloader-bug"

I'll work up a test for that patch and release it soon if it works for you.

[robinvrd]

Sorry about the delay, we tested it and it works!

[rmosolgo]

Glad to hear it -- I just shipped the fix in v2.5.23. Please let me now if it gives you any more trouble!