unable to extract __typename from %dth item in the `_represe

Error message

unable to extract __typename from %dth item in the `_representations` argument

What it means

Error returned when resolving a federated entities query in graphql/schema/wrappers.go when the __typename field cannot be extracted from the item at the given index within the `_representations` argument. Fix by ensuring each representation object includes a valid __typename.

Source

Thrown at graphql/schema/wrappers.go:1724

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{
		TypeDefn: &astType{
			typ:             &ast.Type{NamedType: typename},
			inSchema:        q.op.inSchema,
			dgraphPredicate: q.op.inSchema.dgraphPredicate,

View on GitHub (pinned to 759e242be6)

Solutions

Add `__typename` as a string to every representation object
Ensure the gateway includes __typename when building representations
Check client @client-field handling isn't stripping __typename

Example fix

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

Defensive patterns

Strategy: type-guard

Validate before calling

rep := reps[0].(map[string]interface{})
tn, ok := rep["__typename"].(string)
if !ok || tn == "" { return fmt.Errorf("representation missing __typename") }

Type guard

func hasTypename(v interface{}) bool {
	m, ok := v.(map[string]interface{})
	if !ok { return false }
	s, ok := m["__typename"].(string)
	return ok && s != ""
}

Try / catch

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

Prevention

Always include __typename in every representation object
Configure the gateway to inject __typename into representations
Add a contract test asserting __typename presence in entity payloads

When it happens

Trigger: _entities query whose first representation object omits `__typename` or sets it to a non-string (e.g. null).

Common situations: Hand-crafted federation queries forgetting __typename; custom gateways not injecting __typename into representations.

Related errors

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