cayleygraph/cayley · error

not found

Error message

not found

What it means

errNotFound is the schema loader's sentinel for an object that could not be loaded — either the given ID does not exist in the graph, or the entity found does not satisfy the requested type constraints. Callers should detect it with schema.IsNotFound and treat it as a 'no such entity' condition, not a hard failure.

Source

Thrown at schema/loader.go:17

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.
//

View on GitHub (pinned to 81dcd7d73e)

Solutions

1. Check schema.IsNotFound(err) and handle it as 'entity missing' (create it, return 404, etc.).
2. Verify the node ID/name exists via a direct quad query before loading.
3. Confirm the entity was saved with the expected rdf type (schema.WriteAll or with type constraint).

Example fix

// before
err := schema.LoadTo(ctx, qs, &person, iri)
log.Fatal(err) // crashes on missing entity
// after
if err := schema.LoadTo(ctx, qs, &person, iri); err != nil {
    if schema.IsNotFound(err) {
        return nil, ErrUserNotFound
    }
    return nil, err
}

// ensure node exists before load
pqs := graph.NewQuadStoreIterator(qs, iri)
if !pqs.Next() { return errors.New("node does not exist") }

func isEntityMissing(err error) bool { return schema.IsNotFound(err) }

if err := schema.LoadTo(ctx, qs, &v, iri); err != nil {
    if schema.IsNotFound(err) {
        return ErrEntityNotFound
    }
    return err
}

When it happens

Trigger: Calling schema.LoadTo/schema.LoadByNameTo (via loadIteratorToDepth) with a node ID absent from the store, or with a type that doesn't match the stored entity's types.

Common situations: Requesting a deleted record; wrong IRI/key passed by the client; filtering by a type the entity was never saved as; working against a different database than expected.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

• required field is missing
• expected struct, got %v
• load anonymous field %s failed: %v
• field %s: %v
• can't load rules: %v

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