What causes "quadstore: not initialized" in cayleygraph/cayley?

Run initialization first: cayley init (or graph.Init in code) to create the metadata, then open with New.

ErrNotInitialized

ErrNotInitialized

Error message

quadstore: not initialized

What it means

ErrNotInitialized is the quadstore-level sentinel meaning the database location exists but was never initialized (no metadata). The kv backend translates the internal ErrNoBucket condition into this public error from New, so callers can detect an uninitialized store with errors.Is/graph comparison.

Source

Thrown at graph/quadstore.go:157

	return def, nil
}

func (d Options) BoolKey(key string, def bool) (bool, error) {
	if val, ok := d[key]; ok {
		if v, ok := val.(bool); ok {
			return v, nil
		}

		return def, fmt.Errorf("Invalid %s parameter type from config: %T", key, val)
	}

	return def, nil
}

var (
	ErrDatabaseExists = errors.New("quadstore: cannot init; database already exists")
	ErrNotInitialized = errors.New("quadstore: not initialized")
)

View on GitHub (pinned to 81dcd7d73e)

Solutions

Run initialization first: cayley init (or graph.Init in code) to create the metadata, then open with New.
Verify the configured database path actually points at the initialized data directory.
In code, detect graph.ErrNotInitialized and branch to an init workflow rather than failing.

Example fix

// before
qs, err := graph.New(ctx, opts) // ErrNotInitialized on fresh path
// after
qs, err := graph.New(ctx, opts)
if errors.Is(err, graph.ErrNotInitialized) {
    if err := graph.Init(ctx, opts); err != nil { return err }
    qs, err = graph.New(ctx, opts)
}

Defensive patterns

Strategy: try-catch

Validate before calling

if fi, err := os.Stat(path); err != nil || !fi.IsDir() {
    return fmt.Errorf("database path %q does not exist or is not a directory", path)
}

Try / catch

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

Prevention

Run the init step in deployment pipelines before starting services.
Verify the configured database path points at the initialized volume.
Match against errors.Is(err, graph.ErrNotInitialized) instead of string comparison.

When it happens

Trigger: Calling graph.New / kv.New on a kv path where Init never ran, so getMetadata finds no bucket and the store maps ErrNoBucket to graph.ErrNotInitialized.

Common situations: Pointing cayley at an empty or wrong directory; running queries/server before running init; a fresh volume in a container without the init step in the deployment pipeline.

Related errors

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