dgraph-io/dgraph · error

error while building unique query

Error message

error while building unique query

What it means

For N-Quads whose object is a val(var) variable on a @unique predicate, addQueryIfUnique builds a multi-line DQL query block `X as var(func: eq(P, val(v))){ uid Y as P }`. A WriteString failure while appending this block is wrapped as 'error while building unique query' (edgraph/server.go:1997). Like error 275, it is an internal builder failure triggered from the unique-check query construction path, not a client-side mistake.

Source

Thrown at edgraph/server.go:1997

					continue
				}
				val := strconv.Quote(fmt.Sprintf("%v", dql.TypeValFrom(pred.ObjectValue).Value))
				query := fmt.Sprintf(`%v as var(func: eq(%v,"%v"))`, queryVar, predicateName, val[1:len(val)-1])
				if _, err := buildQuery.WriteString(query); err != nil {
					return errors.Wrapf(err, "error while writing string")
				}
				qc.uniqueVars[uniqueVarMapKey] = uniquePredMeta{queryVar: queryVar}
			} else {
				if err := validateValObjectId(pred.ObjectId); err != nil {
					return err
				}
				valQueryVar := fmt.Sprintf("__dgraph_uniquecheck_val_%v__", uniqueVarMapKey)
				query := fmt.Sprintf(`%v as var(func: eq(%v,%v)){
					                             uid
					                             %v as %v
				                 }`, queryVar, predicateName, pred.ObjectId, valQueryVar, predicateName)
				if _, err := buildQuery.WriteString(query); err != nil {
					return errors.Wrapf(err, "error while building unique query")
				}
				qc.uniqueVars[uniqueVarMapKey] = uniquePredMeta{valVar: valQueryVar, queryVar: queryVar}
			}
		}

		if buildQuery.Len() > 0 {
			if _, err := buildQuery.WriteString("}"); err != nil {
				return errors.Wrapf(err, "error while writing string")
			}
			if qc.req.Query == "" {
				qc.req.Query = "{" + buildQuery.String()
			} else {
				qc.req.Query = strings.TrimSuffix(qc.req.Query, "}")
				qc.req.Query = qc.req.Query + buildQuery.String()
			}
		}
	}
	return nil

View on GitHub (pinned to 759e242be6)

Solutions

1. Retry the mutation; the failure is typically transient (allocation pressure)
2. Check Alpha memory usage/logs for the underlying cause and raise container memory limits if under pressure
3. Restart the Alpha if errors persist
4. File an issue with Dgraph including the wrapped error if it reproduces consistently

err := mutate(ctx, mu)
if err != nil && strings.Contains(err.Error(), "error while building unique query") {
	// internal/transient: retry with backoff; escalate if persistent
}

When it happens

Trigger: Internal strings.Builder write failure while constructing the unique-check query for a mutation N-Quad with object val(varName) on a @unique predicate (edgraph/server.go:1997). Note: an invalid val() reference inside pred.ObjectId is rejected earlier by validateValObjectId with a different error, so this specific message indicates a builder-level failure.

Common situations: Alpha under memory pressure or in a degraded state; essentially never attributable to mutation content beyond it triggering the val()-based unique-check path.

Related errors

• error while writing string
• could not insert duplicate value [%v] for predicate [%v]
• UID must to be greater than 0
• UID not found/generated for xid %s
• Subject and object both should be *. Got: %+v

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