{"record":{"id":"694067f8b0278124","repo":"gastownhall/beads","slug":"node-q-metadata-ref-q-references-unknown-key-q","errorCode":null,"errorMessage":"node %q: metadata ref %q references unknown key %q","messagePattern":"node %q: metadata ref %q references unknown key %q","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/bd/graph_apply.go","lineNumber":562,"sourceCode":"\t\t}\n\t\tif node.ID != \"\" {\n\t\t\tif seenIDs[node.ID] {\n\t\t\t\treturn fmt.Errorf(\"duplicate explicit id %q (node %q)\", node.ID, node.Key)\n\t\t\t}\n\t\t\tseenIDs[node.ID] = true\n\t\t}\n\t\t// Validate MetadataRefs point to known keys.\n\t\tfor metaKey, refKey := range node.MetadataRefs {\n\t\t\tif !seenKeys[refKey] {\n\t\t\t\tfound := false\n\t\t\t\tfor _, other := range plan.Nodes {\n\t\t\t\t\tif other.Key == refKey {\n\t\t\t\t\t\tfound = true\n\t\t\t\t\t\tbreak\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\tif !found {\n\t\t\t\t\treturn fmt.Errorf(\"node %q: metadata ref %q references unknown key %q\", node.Key, metaKey, refKey)\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\tparentKey := node.effectiveParentKey()\n\t\tif parentKey != \"\" && !seenKeys[parentKey] {\n\t\t\tfound := false\n\t\t\tfor _, other := range plan.Nodes {\n\t\t\t\tif other.Key == parentKey {\n\t\t\t\t\tfound = true\n\t\t\t\t\tbreak\n\t\t\t\t}\n\t\t\t}\n\t\t\tif !found {\n\t\t\t\treturn fmt.Errorf(\"node %q: parent key %q not found in plan\", node.Key, parentKey)\n\t\t\t}\n\t\t}\n\t\tfor j, dep := range node.Deps {\n\t\t\tif dep.Target == \"\" {","sourceCodeStart":544,"sourceCodeEnd":580,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/cmd/bd/graph_apply.go#L544-L580","documentation":"A node's `metadata_refs` map values must reference keys of other nodes in the same plan. Validation looks the referenced key up in the seen-keys set (and falls back to scanning plan nodes) and errors if the target key is unknown.","triggerScenarios":"`bd graph apply` where node X has metadata_refs[metaKey] = \"some-key\" but no node with key \"some-key\" exists in the plan.","commonSituations":"Typos in referenced keys; referencing nodes that were deleted from the plan; referencing nodes expected to exist in the tracker instead of the plan (refs must be in-plan).","solutions":["Correct the metadata ref value to match an existing node key in the plan","Add the missing node to plan.nodes if it should exist","Remove the metadata ref if it is no longer needed"],"exampleFix":"// before\n{\"key\": \"deploy\", \"metadata_refs\": {\"blocked_by\": \"db-migrte\"}}\n// after\n{\"key\": \"deploy\", \"metadata_refs\": {\"blocked_by\": \"db-migrate\"}}","handlingStrategy":"validation","validationCode":"keys := map[string]bool{}\nfor _, n := range plan.Nodes { keys[n.Key] = true }\nfor _, n := range plan.Nodes {\n\tfor mk, ref := range n.MetadataRefs {\n\t\tif !keys[ref] { return fmt.Errorf(\"node %s: meta ref %s -> unknown key %s\", n.Key, mk, ref) }\n\t}\n}","typeGuard":null,"tryCatchPattern":"if err := bd.GraphApply(ctx, plan, opts); err != nil {\n\tif strings.Contains(err.Error(), \"references unknown key\") {\n\t\t// repair the metadata ref and retry\n\t}\n}","preventionTips":["Generate metadata refs from node keys programmatically rather than by hand","Validate ref targets against the plan keys before applying","Remove refs when removing referenced nodes"],"tags":["validation","graph-apply","dangling-reference"],"backgroundTag":"unknown-reference-key","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}