dgraph-io/dgraph · error

Missing fragment: %s

Error message

Missing fragment: %s

What it means

expandFragments walks the query tree and replaces fragment-spread children with the fields of the fragment definition looked up in the fragment map (fmap). If a spread references a fragment name that was never defined in the query, fmap lookup returns nil and the library returns this error naming the missing fragment.

Source

Thrown at dql/parser.go:276

	fn.Entered = true
	if err := fn.Gq.expandFragments(fmap); err != nil {
		return err
	}
	fn.Exited = true
	return nil
}

func (gq *GraphQuery) expandFragments(fmap fragmentMap) error {
	// We have to make a copy of children to preserve order and replace
	// fragment references with fragment content. The copy is newChildren.
	var newChildren []*GraphQuery
	// Expand non-fragments. Do not append to gq.Children.
	for _, child := range gq.Children {
		if child.isFragment() {
			fname := child.fragment // Name of fragment being referenced.
			fchild := fmap[fname]
			if fchild == nil {
				return errors.Errorf("Missing fragment: %s", fname)
			}
			if err := fchild.expand(fmap); err != nil {
				return err
			}
			newChildren = append(newChildren, fchild.Gq.Children...)
		} else {
			if err := child.expandFragments(fmap); err != nil {
				return err
			}
			newChildren = append(newChildren, child)
		}
	}
	gq.Children = newChildren
	return nil
}

func convertToVarMap(variables map[string]string) (vm varMap) {
	vm = make(map[string]varInfo)

View on GitHub (pinned to 759e242be6)

Solutions

1. Add the missing 'fragment <name> on <type> { ... }' definition to the query text
2. Check the fragment name in the error message against your spread sites for typos/case mismatches
3. Ensure your query-builder/tooling emits fragment definitions alongside spreads
4. Remove the spread if the fragment is intentionally unavailable and inline the needed fields

Example fix

// before
query { user(func: uid(0x1)) { ...userDetails } }
// after
query { user(func: uid(0x1)) { ...userDetails } }
fragment userDetails on User { name email }

func allFragmentsDefined(query string) error {
  reSpread := regexp.MustCompile(`\.\.\.([A-Za-z_][A-Za-z0-9_]*)`)
  reDef := regexp.MustCompile(`fragment\s+([A-Za-z_][A-Za-z0-9_]*)\s+on`)
  defined := map[string]bool{}
  for _, m := range reDef.FindAllStringSubmatch(query, -1) { defined[m[1]] = true }
  for _, m := range reSpread.FindAllStringSubmatch(query, -1) {
    if !defined[m[1]] { return fmt.Errorf("spread of undefined fragment %s", m[1]) }
  }
  return nil
}

When it happens

Trigger: Executing a DQL query via ParseWithNeedVars containing a spread like '...userDetails' with no corresponding 'fragment userDetails on ...' definition anywhere in the query string.

Common situations: Copy-pasting a query that uses shared fragments without copying the fragment definitions; typos in the fragment name in the spread vs. the definition; stripping fragments in tooling that assembles queries dynamically.

Related errors

• Cycle detected: %s
• error querying persisted queries
• Invalid Math expression
• Invalid math statement. Expected 1 operands
• Division by zero

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