expecting at least one item in `representations` argument

Error message

expecting at least one item in `representations` argument

What it means

Error returned when resolving a federated (_entities-like) query in graphql/schema/wrappers.go when the `representations` argument contains no items. The federation contract requires at least one representation object. Fix by passing a non-empty representations list.

Source

Thrown at graphql/schema/wrappers.go:1716

func (q *query) NullResponse() []byte {
	return (*field)(q).NullResponse()
}

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)
	}

View on GitHub (pinned to 759e242be6)

Solutions

Ensure the query actually requests a field that produces at least one representation
Check federation key/config so the gateway emits representations for the entity
If legitimately empty, guard the caller to skip _entities resolution

Example fix

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

Defensive patterns

Strategy: type-guard

Validate before calling

reps, _ := args["representations"].([]interface{})
if len(reps) == 0 { skipEntities() }

Type guard

func hasRepresentations(v interface{}) bool {
	reps, ok := v.([]interface{})
	return ok && len(reps) > 0
}

Try / catch

entity, err := q.RepresentationsArg()
if err != nil && strings.Contains(err.Error(), "at least one item") {
	return nil, nil // nothing to resolve; skip entities
}

Prevention

Skip _entities resolution when the gateway produces zero representations
Check federation keys so gateways always emit representations when needed
Monitor gateway logs for empty-representation entity batches

When it happens

Trigger: A federation _entities query sent with `representations: []` — usually when the gateway computed no matching entities for a federated field.

Common situations: Gateway routing an entities request where no federated type matched; misconfigured federation key causing zero representations to be collected.

Related errors

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