dgraph-io/dgraph · error

unable to extract value for key field `%s` from %dth item in

Error message

unable to extract value for key field `%s` from %dth item in the `_representations` argument

What it means

After validating __typename, the parser extracts the entity's key field value (e.g. `upc` for Product) from each representation. This error fires when the representation map lacks the key field named by the @key directive on the type at index i.

Source

Thrown at graphql/schema/wrappers.go:1768

	for i, rep := range representations {
		representation, ok = rep.(map[string]interface{})
		if !ok {
			return nil, fmt.Errorf("error parsing %dth item in the `_representations` argument", i)
		}

		typename, ok = representation[Typename].(string)
		if !ok {
			return nil, fmt.Errorf("unable to extract __typename from %dth item in the"+
				" `_representations` argument", i)
		}
		if typename != entityReprs.TypeDefn.Name() {
			return nil, fmt.Errorf("expected only one unique typename in `_representations`"+
				" argument, got: [%s, %s]", entityReprs.TypeDefn.Name(), typename)
		}

		keyVal, ok := representation[keyFldName]
		if !ok {
			return nil, fmt.Errorf("unable to extract value for key field `%s` from %dth item in"+
				" the `_representations` argument", keyFldName, i)
		}
		entityReprs.KeyVals = append(entityReprs.KeyVals, keyVal)
		entityReprs.KeyValToRepresentation[fmt.Sprint(keyVal)] = representation
	}

	return entityReprs, nil
}

func (q *query) AuthFor(jwtVars map[string]interface{}) Query {
	// copy the template, so that multiple queries can run rewriting for the rule.
	return &query{
		field: (*field)(q).field,
		op: &operation{op: q.op.op,
			query:    q.op.query,
			doc:      q.op.doc,
			inSchema: q.op.inSchema,
			vars:     jwtVars,

View on GitHub (pinned to 759e242be6)

Solutions

1. Include the key field defined by the type's @key directive in every representation
2. Check the subgraph schema for the exact key field name (e.g. upc vs sku)
3. Regenerate client types after schema changes so key fields stay in sync

Example fix

// before
{"__typename":"Product"}
// after
{"__typename":"Product","upc":"1"}

keyFields := map[string]string{"Product":"upc","Review":"id"}
for i, rep := range representations {
  tn := rep["__typename"].(string)
  if _, ok := rep[keyFields[tn]]; !ok {
    return fmt.Errorf("rep %d missing key field %s", i, keyFields[tn])
  }
}

When it happens

Trigger: A representation object with correct __typename but missing the key field (e.g. no `upc` for a Product keyed on upc), or the key field present with value nil where the map lookup via keyFldName fails.

Common situations: Partial representations produced by gateways dropping key fields, renamed fields after schema change, or clients constructing representations manually without reading the @key directive.

Related errors

• error parsing `representations` argument
• 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
• type %s not found in the schema

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