value for field `%s` in type `%s` index `%d` must have exact

Error message

value for field `%s` in type `%s` index `%d` must have exactly one child, found %d children

What it means

GraphQL list fields of object type must contain objects, and each value for a field must have exactly one child object in the mutation input. When rewriting a list item (identified by listIndex), Dgraph found an object with a number of keys/children other than one, which it cannot interpret as a single node value. The error reports the field, parent type, list index, and child count.

Source

Thrown at graphql/resolve/mutation_rewriter.go:2031

	return ret, retTypes, retErrors
}

func existenceQueriesUnion(
	ctx context.Context,
	parentTyp schema.Type,
	srcField schema.FieldDefinition,
	varGen *VariableGenerator,
	obj map[string]interface{},
	xidMetadata *xidMetadata,
	listIndex int) ([]*dql.GraphQuery, []string, []error) {

	var retError []error
	if len(obj) != 1 {
		var err error
		// if this was called from rewriteList,
		// the listIndex will tell which particular item in the list has an error.
		if listIndex >= 0 {
			err = fmt.Errorf(
				"value for field `%s` in type `%s` index `%d` must have exactly one child, "+
					"found %d children", srcField.Name(), parentTyp.Name(), listIndex, len(obj))
		} else {
			err = fmt.Errorf(
				"value for field `%s` in type `%s` must have exactly one child, found %d children",
				srcField.Name(), parentTyp.Name(), len(obj))
		}
		retError = append(retError, err)
		return nil, nil, retError
	}

	var newtyp schema.Type
	for memberRef, memberRefVal := range obj {
		memberTypeName := strings.ToUpper(memberRef[:1]) + memberRef[1:len(
			memberRef)-3]
		srcField = srcField.WithMemberType(memberTypeName)
		newtyp = srcField.Type()
		obj = memberRefVal.(map[string]interface{})

View on GitHub (pinned to 759e242be6)

Solutions

Inspect the list item at the reported index and reshape it so each entry contains exactly one child object.
Remove extraneous sibling keys or split them into separate list items.
Regenerate the payload from typed client code (e.g. graphql-codegen) instead of hand-building JSON.
Replace empty objects {} with a properly identified node (id or @id field).

Example fix

// before
posts: [{ title: "a", extra: {} }] // 2 children at index 0
// after
posts: [{ title: "a" }] // exactly one child per list item

Defensive patterns

Strategy: validation

Validate before calling

function assertSingleChildListItems(list) {
  list.forEach((item, i) => {
    if (typeof item !== 'object' || item === null || Object.keys(item).length !== 1) {
      throw new Error(`list index ${i} must have exactly one child, found ${Object.keys(item || {}).length}`);
    }
  });
}

Type guard

function isSingleChildNode(v) {
  return typeof v === 'object' && v !== null && Object.keys(v).length === 1;
}

Try / catch

try {
  await client.mutate({ mutation: ADD, variables: { input } });
} catch (e) {
  if (/must have exactly one child/.test(e.message)) {
    const m = e.message.match(/index `(\d+)`/);
    if (m) console.warn("fix list item at index", m[1]);
  } else throw e;
}

Prevention

Generate mutation payloads with typed clients instead of hand-built JSON.
Validate nested object shapes (one child per value) before sending.
Never put empty objects {} inside list-typed fields.
Test mutations against a dev Dgraph instance before production.

When it happens

Trigger: A mutation input where a list-typed field's item at the given index is an object with zero or multiple sibling keys where exactly one nested node value was expected — typically a malformed nested input structure inside rewriteList.

Common situations: Hand-written mutation JSON with mismatched braces, generators emitting `{ a: {...}, b: {...} }` where `{ a: {...} }` was intended, or empty objects `{}` appearing in lists.

Related errors

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