GraphQL debug: only one node is allowed in the filter while

Error message

GraphQL debug: only one node is allowed in the filter while updating fields with @id directive

What it means

Identical to the non-debug variant: an update on an @id field matched multiple nodes via the upsert query. This version is returned when queryAuthSelector(mutatedType) IS defined (auth/debug context), and prefixes the message with 'GraphQL debug:' so the client can trace which nodes conflicted.

Source

Thrown at graphql/resolve/mutation.go:465

			if len(objSet) != 0 {
				for _, xid := range mutatedType.XIDFields() {
					if xidVal, ok := objSet[xid.Name()]; ok && xidVal != nil {
						xidsPresent = true
					}
				}
			}
			// if @id field is present in set and there are multiple nodes returned from
			// upsert query then we return error
			if xidsPresent && len(result[mutation.Name()].([]interface{})) > 1 {
				if queryAuthSelector(mutatedType) == nil {
					return emptyResult(
							schema.GQLWrapf(errors.Errorf("only one node is allowed in"+
								" the filter while updating fields with @id directive"),
								"mutation %s failed", mutation.Name())),
						resolverFailed
				}
				return emptyResult(
						schema.GQLWrapf(errors.Errorf("GraphQL debug: only one node is"+
							" allowed in the filter while updating fields with @id directive"),
							"mutation %s failed", mutation.Name())),
					resolverFailed

			}
		}

		copyTypeMap(upsert.NewNodes, newNodes)
	}
	mutationTimer.Stop()

	authErr := authorizeNewNodes(ctx, mutation, mutResp.Uids, newNodes, mr.executor, mutResp.Txn)
	if authErr != nil {
		return emptyResult(schema.GQLWrapf(authErr, "mutation failed")), resolverFailed
	}

	var dgQuery []*dql.GraphQuery
	dgQuery, err = mr.mutationRewriter.FromMutationResult(ctx, mutation, mutResp.GetUids(), result)

View on GitHub (pinned to 759e242be6)

Solutions

Deduplicate nodes sharing the @id value
Tighten the filter to a unique @id value
Fix the @auth query rule if it is overly permissive and matching multiple nodes
Investigate how duplicates were created (pre-@id imports, concurrent adds) and prevent recurrence

Example fix

// before
# filter matching several nodes via @auth rule
// after
# use unique @id value so upsert returns exactly one node

Defensive patterns

Strategy: validation

Validate before calling

const nodes = await upsertQuery({ filter });
if (xidsPresent && nodes.length > 1) {
  console.error('GraphQL debug: multiple nodes matched for @id update', nodes);
  throw new Error('narrow the filter to a single node');
}

Try / catch

try {
  await updateMutation(input);
} catch (err) {
  if (err.message.includes('GraphQL debug: only one node is allowed')) {
    // inspect auth rule/filter, dedupe matched nodes
  }
}

Prevention

Keep @auth query rules selective so debug filters match one node
Run with GraphQL debug in staging to catch multi-match filters
Deduplicate nodes sharing @id values
Prefer UID-based filters over broad XID filters for updates

When it happens

Trigger: Update mutation on a type with an @auth query rule where the @id-based upsert filter resolves to more than one node (xidsPresent && result length > 1).

Common situations: Duplicated XIDs in data; @auth query rules on types whose filters match several nodes; running with GraphQL debug enabled surfaces this prefixed variant.

Related errors

AI-assisted analysis of dgraph-io/dgraph@759e242be6 (2026-09-01). Data as JSON: /api/errors/8e36cfe33835c1d0. Report an issue: GitHub.