cayleygraph/cayley · error

ErrNoBucket

ErrNoBucket

Error message

kv: no bucket

What it means

ErrNoBucket is the sentinel error returned by the kv quadstore layer when the expected metadata bucket does not exist. Callers use it to distinguish 'database not initialized' (no metadata bucket) from real failures: New maps it to graph.ErrNotInitialized, and Init checks that the metadata bucket is absent before creating a fresh database.

Source

Thrown at graph/kv/quadstore.go:39

	"errors"
	"fmt"
	"os"
	"sync"

	"github.com/cayleygraph/quad"
	"github.com/cayleygraph/quad/pquads"
	"github.com/hidal-go/hidalgo/kv"
	boom "github.com/tylertreat/BoomFilters"

	"github.com/cayleygraph/cayley/graph"
	"github.com/cayleygraph/cayley/graph/proto"
	"github.com/cayleygraph/cayley/graph/refs"
	"github.com/cayleygraph/cayley/internal/lru"
	"github.com/cayleygraph/cayley/query/shape"
)

var (
	ErrNoBucket  = errors.New("kv: no bucket")
	ErrEmptyPath = errors.New("kv: path to the database must be specified")
)

type Registration struct {
	NewFunc      NewFunc
	InitFunc     InitFunc
	IsPersistent bool
}

type InitFunc func(string, graph.Options) (kv.KV, error)
type NewFunc func(string, graph.Options) (kv.KV, error)

func Register(name string, r Registration) {
	graph.RegisterQuadStore(name, graph.QuadStoreRegistration{
		InitFunc: func(addr string, opt graph.Options) error {
			if !r.IsPersistent {
				return nil
			}

View on GitHub (pinned to 81dcd7d73e)

Solutions

1. Run the Init/create step first (cayley init, or graph.Init) so the metadata bucket is created, then New.
2. Verify the path points at an existing, initialized database directory.
3. In code, treat ErrNoBucket as graph.ErrNotInitialized and branch to initialization logic.

Example fix

// before
qs, err := kv.New(db) // ErrNoBucket on empty database
// after
if err := graph.Init(ctx, opts); err != nil && err != graph.ErrDatabaseExists {
    return err
}
qs, err := kv.New(db)

if _, err := os.Stat(path); os.IsNotExist(err) {
    // database not created yet: run init first
}

qs, err := kv.New(db)
if errors.Is(err, kv.ErrNoBucket) || errors.Is(err, graph.ErrNotInitialized) {
    if err := graph.Init(ctx, opts); err != nil {
        return err
    }
    qs, err = kv.New(db)
}

When it happens

Trigger: Calling kv.New(...) on a kv handle whose metadata bucket was never created (i.e. Init was never run, or a wrong/empty path was opened). Also used internally by Init/New/getSize when probing bucket existence.

Common situations: Opening a database path before running cayley init; pointing at the wrong directory so no bucket exists; a fresh empty file created by the kv backend; deleting the metadata bucket manually.

Related errors

• ErrNotInitialized
• ErrEmptyPath
• kv: data version is out of date. Run cayleyupgrade for your
• ErrDatabaseExists
• no indexes defined

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