What causes "UID must to be greater than 0" in dgraph-io/dgraph?

Validate UIDs before calling mutation APIs: parse and reject any uid <= 0 (or "0x0" strings) in client code.

UID must to be greater than 0

Error message

UID must to be greater than 0

What it means

errInvalidUID is declared in dql/mutation.go and returned by ParseUid and toUid when a UID value is zero or invalid. UIDs in Dgraph must be strictly greater than 0; 0 is reserved as the empty/invalid node id. The library throws it to prevent constructing edges or mutations against a non-existent node.

Source

Thrown at dql/mutation.go:20

 * SPDX-FileCopyrightText: © 2017-2026 Istari Digital, Inc.
 * SPDX-License-Identifier: Apache-2.0
 */

package dql

import (
	"strconv"

	"github.com/pkg/errors"

	"github.com/dgraph-io/dgo/v250/protos/api"
	"github.com/dgraph-io/dgraph/v25/protos/pb"
	"github.com/dgraph-io/dgraph/v25/types"
	"github.com/dgraph-io/dgraph/v25/x"
)

var (
	errInvalidUID = errors.New("UID must to be greater than 0")
)

// Mutation stores the strings corresponding to set and delete operations.
type Mutation struct {
	Cond         string
	Set          []*api.NQuad
	Del          []*api.NQuad
	AllowedPreds []string

	Metadata *pb.Metadata
}

// ParseUid parses the given string into an UID. This method returns with an error
// if the string cannot be parsed or the parsed UID is zero.
func ParseUid(xid string) (uint64, error) {
	// If string represents a UID, convert to uint64 and return.
	uid, err := strconv.ParseUint(xid, 0, 64)
	if err != nil {

View on GitHub (pinned to 759e242be6)

Solutions

Validate UIDs before calling mutation APIs: parse and reject any uid <= 0 (or "0x0" strings) in client code.
Ensure xid-to-UID lookups check for 'not found' and return an explicit error rather than a zero value UID.
If assigning UIDs yourself, start from 1 (Dgraph allocates leases starting at 1).
Use ParseUid's error return to surface a user-facing message instead of letting 0 reach the edge construction.

Example fix

// before
uid := uint64(0)
edge := &pb.DirectedEdge{Entity: uid} // invalid
// after
if uid == 0 {
    return errors.New("valid UID required; got 0")
}
edge := &pb.DirectedEdge{Entity: uid}

Defensive patterns

Strategy: validation

Validate before calling

func validUid(u uint64) bool { return u > 0 }
func validUidStr(s string) bool {
    n, err := strconv.ParseUint(strings.TrimPrefix(s, "0x"), 0, 64)
    return err == nil && n > 0
}

Type guard

func isUID(v uint64) bool { return v > 0 }
// usage: if !isUID(uid) { return ErrInvalidUID }

Try / catch

uid, err := dql.ParseUid(s)
if err != nil {
    if errors.Is(err, dql.ErrInvalidUID) || strings.Contains(err.Error(), "greater than 0") {
        return fmt.Errorf("rejecting zero/invalid UID input %q", s)
    }
    return err
}

Prevention

Reject UID 0 / "0x0" at the API boundary before building mutations.
Treat failed xid lookups as errors, not zero UIDs.
Remember Dgraph UIDs start at 1; never initialize counters at 0.

When it happens

Trigger: Calling ParseUid with a string that parses to 0 (e.g. "0x0", "0") or toUid receiving a generated/looked-up UID of 0 during mutation processing (`UID must to be greater than 0`).

Common situations: Parsing user-supplied hex UIDs where "0x0" slipped through client validation, an upsert/xid lookup that returned no row and defaulted to 0, or a client that initializes its UID counter at 0 instead of 1.

Related errors

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