dgraph-io/dgraph · error

while converting to subgraph

Error message

while converting to subgraph

What it means

This error wraps any failure that occurs while converting a parsed GraphQL+- query block into an internal SubGraph execution structure (query.ToSubGraph). It fires during query processing when the root query is valid enough to attempt conversion but ToSubGraph encounters an unsupported or inconsistent query shape. The wrap adds context to the underlying conversion error.

Source

Thrown at query/query.go:2882

	stop := x.SpanTimer(span, "query.ProcessQuery")
	defer stop()

	// Vars stores the processed variables.
	req.Vars = make(map[string]varValue)
	loopStart := time.Now()
	queries := req.DqlQuery.Query
	// first loop converts queries to SubGraph representation and populates ReadTs And Cache.
	for i := range queries {
		gq := queries[i]

		if gq == nil || (len(gq.UID) == 0 && gq.Func == nil && len(gq.NeedsVar) == 0 &&
			gq.Alias != "shortest" && !gq.IsEmpty) {
			return errors.Errorf("Invalid query. No function used at root and no aggregation" +
				" or math variables found in the body.")
		}
		sg, err := ToSubGraph(ctx, gq)
		if err != nil {
			return errors.Wrapf(err, "while converting to subgraph")
		}
		sg.recurse(func(sg *SubGraph) {
			sg.ReadTs = req.ReadTs
			sg.Cache = req.Cache
		})
		span.AddEvent("Query parsed")
		req.Subgraphs = append(req.Subgraphs, sg)
	}
	req.Latency.Parsing += time.Since(loopStart)

	execStart := time.Now()
	hasExecuted := make([]bool, len(req.Subgraphs))
	numQueriesDone := 0

	// canExecute returns true if a query block is ready to execute with all the variables
	// that it depends on are already populated or are defined in the same block.
	canExecute := func(idx int) bool {
		queryVars := req.DqlQuery.QueryVars[idx]

View on GitHub (pinned to 759e242be6)

Solutions

1. Inspect the wrapped inner error in the message chain for the actual conversion failure cause
2. Simplify the query: run only the root predicates first, then add features back one at a time
3. Verify query syntax against DQL docs for your Dgraph version (root function/aggregation rules changed across versions)
4. If using root functions like eq/anyofterms, confirm the predicate is indexed

Example fix

// before (invalid mix at root)
{
  me(func: uid(0x1)) @filter(eq(name, "x")) {
    ~parent { uid }
  }
}
// after: use func at root or move filter to body
{
  me(func: eq(name, "x")) {
    ~parent { uid }
  }
}

// Validate query syntax before sending
dql := `{ me(func: eq(name, "x")) { name } }`
if !strings.Contains(dql, "func:") && !strings.Contains(dql, "as var") {
    return errors.New("root must have a function or aggregation")
}

resp, err := dg.NewTxn().Query(ctx, dql)
if err != nil {
    if strings.Contains(err.Error(), "while converting to subgraph") {
        // log full wrapped chain, simplify query and retry
    }
    return err
}

When it happens

Trigger: Calling Dgraph query HTTP /query or gRPC Query with a root query that ToSubGraph rejects: unsupported root functions, malformed aggregation/math variable usage, invalid query syntax that still parses, or invalid combinations of query features at root.

Common situations: Typing a query with an unsupported root construct (e.g. a root function mixed incorrectly with aggregates), version differences where a syntax is no longer supported at root, or programmatically generated DQL with malformed body variables.

Related errors

• Invalid Math expression
• Invalid math statement. Expected 1 operands
• Division by zero
• Invalid Math expression. Expected 3 operands
• Invalid Math expression. Expected 2 operands

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