cayleygraph/cayley · error

kv: data version is out of date. Run cayleyupgrade for your…

Error message

kv: data version is out of date. Run cayleyupgrade for your config to update the data

What it means

The kv quadstore records a data-format version in its metadata bucket. New compares the on-disk version against latestDataVersion and, on mismatch, refuses to open the store, telling the user to migrate the data with cayleyupgrade instead of reading possibly incompatible layout.

Solutions

1. Run cayleyupgrade against your config to migrate the data to the current version.
2. Back up the database directory before upgrading, then re-run the upgrade.
3. Alternatively, re-export and re-initialize the data with the new version (cayley dump + init + load).

// before opening, check version metadata yourself if you control the data layout
// otherwise detect via error

qs, err := kv.New(db)
if err != nil && strings.Contains(err.Error(), "data version is out of date") {
    return fmt.Errorf("run 'cayleyupgrade' to migrate the database before starting: %w", err)
}

When it happens

Trigger: Opening an existing kv database with graph/kv.New (or NewQuadStore) whose stored metadata version differs from latestDataVersion — typically data written by an older Cayley release being opened by a newer one.

Common situations: Upgrading Cayley binaries without migrating the data directory; copying an old database into a new deployment; running a newer cayley server against an old leveldb/badger/bbolt data folder.

Related errors

• ErrEmptyPath
• ErrNoBucket
• blank node ID must start with "_:"
• can not parse JSON-LD identifier: %#v
• can not parse %#v as a literal

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

Appendix: source

Thrown at graph/kv/quadstore.go:169

	if err := qs.writeIndexesMeta(ctx); err != nil {
		return err
	}
	return nil
}

const (
	OptNoBloom = "no_bloom"
)

func New(kv kv.KV, opt graph.Options) (graph.QuadStore, error) {
	ctx := context.TODO()
	qs := newQuadStore(kv)
	if vers, err := qs.getMetadata(ctx); err == ErrNoBucket {
		return nil, graph.ErrNotInitialized
	} else if err != nil {
		return nil, err
	} else if vers != latestDataVersion {
		return nil, errors.New("kv: data version is out of date. Run cayleyupgrade for your config to update the data")
	}
	list, err := qs.readIndexesMeta(ctx)
	if err != nil {
		return nil, err
	}
	qs.indexes.all = list
	qs.valueLRU = lru.New(2000)
	qs.exists.disabled, _ = opt.BoolKey(OptNoBloom, false)
	if err := qs.initBloomFilter(ctx); err != nil {
		return nil, err
	}
	if !qs.exists.disabled {
		if sz, err := qs.getSize(); err != nil {
			return nil, err
		} else if sz == 0 {
			qs.mapBloom = make(map[string]*boom.BloomFilter)
			qs.mapNodes = boom.NewBloomFilter(100*1000*1000, 0.05)
		}

View on GitHub (pinned to 81dcd7d73e)