What causes "field %s cannot be empty" in dgraph-io/dgraph?

Omit the @id field entirely from the mutation input when no value is available, instead of sending an empty string.

field %s cannot be empty

Error message

field %s cannot be empty

What it means

A field marked with @id (external ID / XID) was provided with an empty value in a mutation. Dgraph requires @id fields to carry a non-empty value because they are used for existence queries and node references. This variant is thrown for objects in mutation input where the XID field resolved to an empty value.

Source

Thrown at graphql/resolve/mutation_rewriter.go:1573

				xidType := xid.Type().String()
				if xidVal, ok := obj[xid.Name()]; ok && xidVal != nil {
					// This is handled in the for loop above
					continue
				} else if (mutationType == Add || mutationType == AddWithUpsert || !atTopLevel) &&
					(xidType == "String!" || xidType == "Int!" || xidType == "Int64!") {
					// When we reach this stage we are absolutely sure that this is not a reference and is
					// a new node and one of the XIDs is missing.
					// There are two possibilities here:
					// 1. This is an Add Mutation or we are at some deeper level inside Update Mutation:
					//    In this case this is an error as XID field if referenced anywhere inside Add Mutation
					//    or at deeper levels in Update Mutation has to be present. If multiple xids are not present
					//    then we return error for only one.
					// 2. This is an Update Mutation and we are at top level:
					//    In this case this is not an error as the UID at top level of Update Mutation is
					//    referenced as uid(x) in mutations. We don't throw an error in this case and continue
					//    with the function.

					err := errors.Errorf("field %s cannot be empty", xid.Name())
					retErrors = append(retErrors, err)
					return nil, upsertVar, retErrors
				}
			}
		}
	}

	action := defaultDirectiveUpdateAct

	// This is not an XID reference. This is also not a UID reference.
	// This is definitely a new node.
	// Create new node
	if variable == "" {
		// This will happen in case when this is a new node and does not contain XID.
		variable = varGen.Next(typ, "", "", false)
	}

	// myUID is used for referencing this node. It is set to _:variable

View on GitHub (pinned to 759e242be6)

Solutions

Omit the @id field entirely from the mutation input when no value is available, instead of sending an empty string.
Send null or drop the field in client code before serializing the GraphQL request.
If the field should be optional, remove the @id directive from the schema and redeploy it.
Validate input on the client: reject empty strings for fields declared with @id.

Example fix

// before
addUser(input: { name: "Bob", username: "" })
// after
addUser(input: { name: "Bob" }) // omit the empty @id field

Defensive patterns

Strategy: validation

Validate before calling

const xidFields = ["username", "email"];
function assertNoEmptyXids(input) {
  for (const f of xidFields) {
    if (input[f] === "") throw new Error(`field ${f} cannot be empty; omit it or provide a value`);
  }
}

Type guard

function isNonEmptyString(v) {
  return typeof v === 'string' && v.trim().length > 0;
}

Try / catch

try {
  await client.mutate({ mutation: ADD_USER, variables: { input } });
} catch (e) {
  if (/field \w+ cannot be empty/.test(e.message)) {
    const field = e.message.match(/field (\w+)/)[1];
    delete input[Object.keys(input).find(k => k === field)];
  } else throw e;
}

Prevention

Strip empty strings from mutation payloads before sending.
Validate @id fields with a non-empty-string check on the client.
Only mark fields @id in the schema if they are truly mandatory identifiers.
Normalize form submissions: convert '' to undefined.

When it happens

Trigger: Sending an add or update mutation whose nested input object includes an @id field (e.g. `username`) set to "", or where the client omitted a value but the field object was still constructed and passed to the rewriter.

Common situations: Client forms submitting blank strings instead of omitting the field, deserialization frameworks materializing empty strings for missing values, or template-driven mutations interpolating an empty variable.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

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