cayleygraph/cayley · error

required field is missing

Error message

required field is missing

What it means

errRequiredFieldIsMissing is returned when loading or saving a mapped Go struct whose schema defines a required (non-optional) field, but the graph holds no value for it. It is treated as a not-found-class error (schema.IsNotFound returns true) because the object is effectively incomplete for the requested type.

Source

Thrown at schema/loader.go:18

package schema

import (
	"context"
	"errors"
	"fmt"
	"reflect"

	"github.com/cayleygraph/cayley/query/path"
	"github.com/cayleygraph/quad"

	"github.com/cayleygraph/cayley/graph"
	"github.com/cayleygraph/cayley/graph/iterator"
)

var (
	errNotFound               = errors.New("not found")
	errRequiredFieldIsMissing = errors.New("required field is missing")
)

// Optimize flags controls an optimization step performed before queries.
var Optimize = true

// IsNotFound check if error is related to a missing object (either because of wrong ID or because of type constrains).
func IsNotFound(err error) bool {
	return err == errNotFound || err == errRequiredFieldIsMissing
}

// LoadTo will load a sub-graph of objects starting from ids (or from any nodes, if empty)
// to a destination Go object. Destination can be a struct, slice or channel.
//
// Mapping to quads is done via Go struct tag "quad" or "json" as a fallback.
//
// A simplest mapping is an "@id" tag which saves node ID (subject of a quad) into tagged field.
//
//	type Node struct{

View on GitHub (pinned to 81dcd7d73e)

Solutions

1. Add the missing field value to the graph (re-save the entity with all required fields).
2. Mark the field optional in the schema tag so loading tolerates missing values.
3. Use schema.IsNotFound(err) to handle incomplete records gracefully instead of failing.

Example fix

// before
type Person struct {
    Name string `cayley:"schema:name"` // required, missing in DB
}
// after
type Person struct {
    Name string `cayley:"schema:name,opt"` // or write the name quad
}

// check required field has a value in the graph before load
if len(valuesFor(qs, iri, schemaName)) == 0 {
    return errors.New("required field 'name' missing for " + iri)
}

func isIncompleteRecord(err error) bool {
    return schema.IsNotFound(err) && err.Error() == "required field is missing"
}

err := schema.LoadTo(ctx, qs, &obj, iri)
if err != nil && err.Error() == "required field is missing" {
    // handle partial record: backfill, default, or skip
}

When it happens

Trigger: Loading a struct where a non-optional field (e.g. without schema:"-,opt" / not registered optional) has no quads in the graph (loadToValue/loadIteratorToDepth); saving rules in loadIteratorToDepth encountering an empty required field map.

Common situations: Partial writes that skipped a required property; entities created by another tool that doesn't set all fields; schema evolution adding a new required field to old data.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• not found
• multiple fields at location root %s
• expected struct, got %v
• load anonymous field %s failed: %v
• field %s: %v

AI-assisted analysis of cayleygraph/cayley@81dcd7d73e (2026-09-06). Data as JSON: /api/errors/9cbba7f268268316. Report an issue: GitHub.