dgraph-io/dgraph · error

unique validation failed to fetch schema for predicates %v

Error message

unique validation failed to fetch schema for predicates %v

What it means

Before building unique-check queries, addQueryIfUnique must know whether each mutated predicate is unique. If the predicate's schema is not cached locally, Dgraph fetches it over the network from other Alpha nodes via GetSchemaOverNetwork; a transport/consensus failure there is wrapped with this message (edgraph/server.go:1906). The mutation itself is aborted because uniqueness cannot be verified. The underlying cause is carried in the wrapped error.

Source

Thrown at edgraph/server.go:1906

			}
			fullPred := x.NamespaceAttr(currNs, pred.Predicate)
			if _, ok := schema.State().Get(ctx, fullPred); !ok {
				missingPreds[fullPred] = struct{}{}
			}
		}
	}

	repaired := make(map[string]bool)
	if len(missingPreds) > 0 {
		predList := make([]string, 0, len(missingPreds))
		for p := range missingPreds {
			predList = append(predList, p)
		}

		schReq := &pb.SchemaRequest{Predicates: predList}
		remoteNodes, err := worker.GetSchemaOverNetwork(ctx, schReq)
		if err != nil {
			return errors.Wrapf(err, "unique validation failed to fetch schema for predicates %v", predList)
		}

		for _, node := range remoteNodes {
			repaired[node.Predicate] = node.Unique
		}
	}

	qc.uniqueVars = map[uint64]uniquePredMeta{}
	for gmuIndex, gmu := range qc.gmuList {
		var buildQuery strings.Builder
		for rdfIndex, pred := range gmu.Set {
			if isGalaxyQuery {
				// The caller should make sure that the directed edges contain the namespace we want
				// to insert into.
				namespace = pred.Namespace
			}
			if pred.Predicate != "dgraph.xid" {
				// [TODO] Don't check if it's dgraph.xid. It's a bug as this node might not be aware

View on GitHub (pinned to 759e242be6)

Solutions

1. Read the wrapped cause: if it is connection refused/timeouts, check cluster health (curl /health, alpha endpoints, Zero raft state) and restore connectivity
2. Retry the mutation once the cluster is healthy — this is typically transient
3. Ensure all Alphas are on the same version and joined to the same Zero group so schema propagation works
4. Check TLS/mutual-auth settings between nodes; mismatched certs cause schema-over-network fetch failures
5. Avoid mutations during rolling restarts; wait for all Alphas to report healthy

err := mutate(ctx, mu)
if err != nil && strings.Contains(err.Error(), "unique validation failed to fetch schema") {
	// transient cluster issue: retry with backoff
	time.Sleep(backoff)
	return mutate(ctx, mu)
}

When it happens

Trigger: A mutation on a predicate not present in the local schema cache while the cluster cannot serve the schema request — leader unreachable, Raft quorum lost, network partition between Alphas, or the request hitting an Alpha that cannot reach the Zero/Alpha holding the schema during the mutation path (edgraph/server.go:1906).

Common situations: Rolling restarts or node down in the cluster; new Alpha joining before it syncs schema; network misconfiguration (firewall, TLS mismatch) between Alphas; cluster degraded after Zero leader election; sending mutations to a stale/rejoined node.

Related errors

• while fetching schema
• while fetching types
• cannot retrieve predicate information
• illegal rune found "%c", expecting {
• JSON map is followed by illegal rune "%c"

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