{"record":{"id":"682a3e46793fbd0f","repo":"cayleygraph/cayley","slug":"kv-data-version-is-out-of-date-run-cayleyupgrade","errorCode":null,"errorMessage":"kv: data version is out of date. Run cayleyupgrade for your config to update the data","messagePattern":"kv: data version is out of date\\. Run cayleyupgrade for your config to update the data","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"graph/kv/quadstore.go","lineNumber":169,"sourceCode":"\tif err := qs.writeIndexesMeta(ctx); err != nil {\n\t\treturn err\n\t}\n\treturn nil\n}\n\nconst (\n\tOptNoBloom = \"no_bloom\"\n)\n\nfunc New(kv kv.KV, opt graph.Options) (graph.QuadStore, error) {\n\tctx := context.TODO()\n\tqs := newQuadStore(kv)\n\tif vers, err := qs.getMetadata(ctx); err == ErrNoBucket {\n\t\treturn nil, graph.ErrNotInitialized\n\t} else if err != nil {\n\t\treturn nil, err\n\t} else if vers != latestDataVersion {\n\t\treturn nil, errors.New(\"kv: data version is out of date. Run cayleyupgrade for your config to update the data\")\n\t}\n\tlist, err := qs.readIndexesMeta(ctx)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\tqs.indexes.all = list\n\tqs.valueLRU = lru.New(2000)\n\tqs.exists.disabled, _ = opt.BoolKey(OptNoBloom, false)\n\tif err := qs.initBloomFilter(ctx); err != nil {\n\t\treturn nil, err\n\t}\n\tif !qs.exists.disabled {\n\t\tif sz, err := qs.getSize(); err != nil {\n\t\t\treturn nil, err\n\t\t} else if sz == 0 {\n\t\t\tqs.mapBloom = make(map[string]*boom.BloomFilter)\n\t\t\tqs.mapNodes = boom.NewBloomFilter(100*1000*1000, 0.05)\n\t\t}","sourceCodeStart":151,"sourceCodeEnd":187,"githubUrl":"https://github.com/cayleygraph/cayley/blob/81dcd7d73e45136bc0d01802a8ba4685d8a533eb/graph/kv/quadstore.go#L151-L187","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Run cayleyupgrade against your config to migrate the data to the current version.","Back up the database directory before upgrading, then re-run the upgrade.","Alternatively, re-export and re-initialize the data with the new version (cayley dump + init + load)."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// before opening, check version metadata yourself if you control the data layout\n// otherwise detect via error","typeGuard":null,"tryCatchPattern":"qs, err := kv.New(db)\nif err != nil && strings.Contains(err.Error(), \"data version is out of date\") {\n    return fmt.Errorf(\"run 'cayleyupgrade' to migrate the database before starting: %w\", err)\n}","preventionTips":["Always run cayleyupgrade after upgrading the Cayley binary.","Back up the data directory before version upgrades.","Pin cayleygraph library versions in go.mod to match your on-disk data version.","Add a pre-start check that runs the upgrade step in deployment scripts."],"tags":["go","kv-store","migration","version-mismatch"],"backgroundTag":"schema-version-mismatch","analyzedSha":"81dcd7d73e45136bc0d01802a8ba4685d8a533eb","analyzedAt":"2026-09-06T06:14:12.358Z","contentChangedAt":"2026-09-06T06:14:12.358Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}