dgraph-io/dgraph · error

error parsing `representations` argument

Error message

error parsing `representations` argument

What it means

RepresentationsArg parses the `representations` argument of the federated `_entities` query. This error is thrown when the argument value is not a []interface{} (list), meaning the client sent malformed or missing representations data.

Source

Thrown at graphql/schema/wrappers.go:1713

	return (*field)(q).NullValue()
}

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)

View on GitHub (pinned to 759e242be6)

Solutions

1. Send `representations` as a JSON array of objects in the _entities query
2. Verify the subgraph schema defines the federated `_service`/`_entities` contract correctly
3. Rebuild/republish the supergraph so gateway and subgraph schemas agree

Example fix

// before
{ _entities(representations: {__typename: "Product", id: "1"}) ... }
// after
{ _entities(representations: [{__typename: "Product", id: "1"}]) ... }

if reps, ok := args["representations"].([]interface{}); !ok || len(reps) == 0 {
	return fmt.Errorf("representations must be a non-empty list")
}

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

entity, err := q.RepresentationsArg()
if err != nil {
	if strings.Contains(err.Error(), "error parsing `representations`") {
		return nil, fmt.Errorf("bad _entities request: %w", err)
	}
	return nil, err
}

When it happens

Trigger: A federation _entities query whose `representations` argument is absent, null, or not a list (e.g. a single object instead of an array).

Common situations: A gateway/supergraph sending entities queries to a subgraph that isn't federation-enabled or whose schema disagrees with the gateway; hand-crafted _entities queries omitting representations.

Related errors

• expecting at least one item in `representations` argument
• error parsing %dth item in the `_representations` argument
• unable to extract __typename from %dth item in the `_represe
• remote %s `%s` accepts %d arguments, It must have only one a
• argument `%s` is not present in remote %s `%s`.

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