{"record":{"id":"12dba144fa0b3589","repo":"gastownhall/beads","slug":"key-cannot-start-with-reserved-prefix-q","errorCode":null,"errorMessage":"key cannot start with reserved prefix %q","messagePattern":"key cannot start with reserved prefix %q","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/bd/kv.go","lineNumber":45,"sourceCode":"\t// Prevent keys that would create nested kv.kv.* prefixes\n\tif strings.HasPrefix(key, kvPrefix) {\n\t\treturn fmt.Errorf(\"key cannot start with 'kv.' (would create nested prefix)\")\n\t}\n\t// Reserve the persistent-memory namespace: a generic memory.* key would\n\t// store to kv.memory.*, indistinguishable from a `bd remember` memory, and\n\t// the merge resolver auto-resolves kv.memory.* conflicts with --theirs\n\t// (GH#2474). Without this guard a user's deliberate kv value could be\n\t// silently overridden by a remote on pull. Keep the namespace owned by\n\t// bd remember / bd forget.\n\tif strings.HasPrefix(key, kvkeys.MemoryPrefix) {\n\t\treturn fmt.Errorf(\"key cannot start with %q (reserved for persistent memories; use 'bd remember' / 'bd forget')\", kvkeys.MemoryPrefix)\n\t}\n\t// Prevent keys that look like internal config\n\tif strings.HasPrefix(key, \"sync.\") || strings.HasPrefix(key, \"conflict.\") ||\n\t\tstrings.HasPrefix(key, \"federation.\") || strings.HasPrefix(key, \"jira.\") ||\n\t\tstrings.HasPrefix(key, \"linear.\") || strings.HasPrefix(key, \"export.\") ||\n\t\tstrings.HasPrefix(key, \"import.\") {\n\t\treturn fmt.Errorf(\"key cannot start with reserved prefix %q\", strings.Split(key, \".\")[0]+\".\")\n\t}\n\treturn nil\n}\n\n// printKVSetResult renders the `bd kv set` success output. Shared by the\n// classic and proxied-server paths so the output shape cannot drift.\nfunc printKVSetResult(key, value string) error {\n\tif jsonOutput {\n\t\treturn outputJSON(map[string]string{\n\t\t\t\"key\":   key,\n\t\t\t\"value\": value,\n\t\t})\n\t}\n\tfmt.Printf(\"Set %s = %s\\n\", key, value)\n\treturn nil\n}\n\n// printKVGetResult renders the `bd kv get` output (including the not-found","sourceCodeStart":27,"sourceCodeEnd":63,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/cmd/bd/kv.go#L27-L63","documentation":"Several key prefixes (sync., conflict., federation., jira., linear., export., import.) are reserved for internal bd configuration. A user key with one of these prefixes could collide with internal state, so validateKVKey rejects it and reports the offending prefix.","triggerScenarios":"Running `bd kv set sync.mykey ...`, `bd kv set export.flag ...`, or any key whose first dot-delimited segment matches a reserved prefix.","commonSituations":"Integration scripts mirroring internal config keys; users poking at internal settings they saw in the database or docs.","solutions":["Choose a non-reserved key, e.g. prefix your own keys with something like `user.` or `custom.`.","If you need to change internal behavior, use the corresponding bd command/flag rather than writing config keys directly.","Inspect the validator in cmd/bd/kv.go for the full list of reserved prefixes."],"exampleFix":"// before\nbd kv set export.format json   // rejected\n// after\nbd kv set user.export-format json","handlingStrategy":"validation","validationCode":"for p in sync. conflict. federation. jira. linear. export. import.; do\n  case \"$KEY\" in \"$p\"*) echo \"reserved prefix: $p\" >&2; exit 1;; esac\ndone\nbd kv set \"$KEY\" \"$VALUE\"","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Namespace user keys under a safe prefix of your own.","Consult cmd/bd/kv.go for the authoritative reserved-prefix list.","Do not attempt to write internal config through kv set."],"tags":["cli","validation","kv-store","reserved-namespace"],"backgroundTag":"reserved-namespace-conflict","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}