error parsing %dth item in the `_representations` argument

Error message

error parsing %dth item in the `_representations` argument

What it means

After confirming the representations list, RepresentationsArg parses the first item and requires it to be a map (object). This error is thrown when representations[0] is not an object (e.g. a scalar or null).

Source

Thrown at graphql/schema/wrappers.go:1720

func (q *query) CompleteAlias(buf *bytes.Buffer) {
	(*field)(q).CompleteAlias(buf)
}

func (q *query) GetAuthMeta() *authorization.AuthMeta {
	return (*field)(q).GetAuthMeta()
}

func (q *query) RepresentationsArg() (*EntityRepresentations, error) {
	representations, ok := q.ArgValue("representations").([]interface{})
	if !ok {
		return nil, fmt.Errorf("error parsing `representations` argument")
	}
	if len(representations) == 0 {
		return nil, fmt.Errorf("expecting at least one item in `representations` argument")
	}
	representation, ok := representations[0].(map[string]interface{})
	if !ok {
		return nil, fmt.Errorf("error parsing %dth item in the `_representations` argument", 0)
	}
	typename, ok := representation[Typename].(string)
	if !ok {
		return nil, fmt.Errorf("unable to extract __typename from %dth item in the"+
			" `_representations` argument", 0)
	}
	typ := q.op.inSchema.schema.Types[typename]
	if typ == nil {
		return nil, fmt.Errorf("type %s not found in the schema", typename)
	}
	keyDir := typ.Directives.ForName(apolloKeyDirective)
	if keyDir == nil {
		return nil, fmt.Errorf("type %s doesn't have a key Directive", typename)
	}
	keyFldName := keyDir.Arguments[0].Value.Raw

	// initialize the struct to return
	entityReprs := &EntityRepresentations{

View on GitHub (pinned to 759e242be6)

Solutions

Make each representation a JSON object containing `__typename`
Validate the payload the gateway sends to the subgraph
Republish the supergraph if the gateway is producing malformed representations

Example fix

// before
representations: ["product-1"]
// after
representations: [{__typename: "Product", id: "product-1"}]

Defensive patterns

Strategy: type-guard

Validate before calling

for _, r := range reps {
	if _, ok := r.(map[string]interface{}); !ok {
		return fmt.Errorf("each representation must be an object")
	}
}

Type guard

func isRepresentation(v interface{}) bool {
	_, ok := v.(map[string]interface{})
	return ok
}

Try / catch

entity, err := q.RepresentationsArg()
if err != nil && strings.Contains(err.Error(), "_representations argument") {
	return nil, fmt.Errorf("malformed representation item: %w", err)
}

Prevention

Ensure representations are JSON objects, never scalars or null
Add gateway-side serialization tests for representation payloads
Validate the entities payload shape at the gateway before forwarding

When it happens

Trigger: _entities query where the first element of `representations` is a non-object value such as a string, number, or null.

Common situations: Malformed hand-written _entities queries; a buggy gateway serializing representations incorrectly.

Related errors

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