dagger/dagger · error

unknown fragment: %s

Error message

unknown fragment: %s

What it means

A GraphQL fragment spread references a fragment definition that does not exist in the operation document (gqlOp.Doc.Fragments.ForName returns nil). dagql requires the spread to resolve to a declared fragment.

Source

Thrown at dagql/server.go:2544

				return nil, fmt.Errorf("parse field %q: %w", x.Name, err)
			}
			var subsels []Selection
			if len(x.SelectionSet) > 0 {
				subsels, err = s.parseASTSelections(ctx, gqlOp, resType, x.SelectionSet)
				if err != nil {
					return nil, err
				}
			}

			sels = append(sels, Selection{
				Alias:         x.Alias,
				Selector:      sel,
				Subselections: subsels,
			})
		case *ast.FragmentSpread:
			fragment := gqlOp.Doc.Fragments.ForName(x.Name)
			if fragment == nil {
				return nil, fmt.Errorf("unknown fragment: %s", x.Name)
			}
			// Check type condition: only include if the fragment's type matches
			// the current object type (or is empty / matches an interface).
			if s.typeConditionMatches(fragment.TypeCondition, self.Name()) {
				if len(fragment.SelectionSet) > 0 {
					// Parse against the fragment's type condition if it differs
					// from the current context (e.g. narrowing from an interface).
					fragSelf := self
					if fragment.TypeCondition != "" && fragment.TypeCondition != self.Name() {
						fragSelf = &ast.Type{NamedType: fragment.TypeCondition, NonNull: true}
					}
					subsels, err := s.parseASTSelections(ctx, gqlOp, fragSelf, fragment.SelectionSet)
					if err != nil {
						return nil, err
					}
					subsels = addTypeCondition(subsels, fragment.TypeCondition)
					sels = append(sels, subsels...)
				}

View on GitHub (pinned to 82ba2681db)

Solutions

1. Add the missing `fragment FragmentName on Type { ... }` definition to the query document
2. Fix the spelling mismatch between the spread and the fragment definition
3. If building queries in code, ensure fragment definitions are collected and attached to the operation
4. Run the query through a graphql parser/validator before sending

Example fix

// before
{ node(id: "x") { ...TreeFields } }
// after
fragment TreeFields on Node { id name }
{ node(id: "x") { ...TreeFields } }

for _, spread := range collectSpreads(doc) {
    if doc.Fragments.ForName(spread.Name) == nil {
        return fmt.Errorf("document references undefined fragment %s", spread.Name)
    }
}

When it happens

Trigger: A query sends `...FragmentName` in a selection set but the fragment `fragment FragmentName on X { ... }` is missing from the document, or its name is misspelled.

Common situations: Programmatically built queries omitting the fragment definition while spreading it; string concatenation of query parts dropping fragments; renaming a fragment in one place only.

Related errors

• patch object function enum defaults: %w
• patch object typedef enum defaults: %w
• missing required address argument
• failed to decode field: %w
• failed to decode function: %w

AI-assisted analysis of dagger/dagger@82ba2681db (2026-09-05). Data as JSON: /api/errors/f20d96399ded28bc. Report an issue: GitHub.