{"record":{"id":"3d756221c74da8a0","repo":"gastownhall/beads","slug":"ambiguous-bootstrap-match-for-ado-s-d-candidat","errorCode":null,"errorMessage":"Ambiguous bootstrap match for ADO #%s: %d candidates","messagePattern":"Ambiguous bootstrap match for ADO #(.+?): (.+?) candidates","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"cmd/bd/ado.go","lineNumber":927,"sourceCode":"\t\t\t// Try bootstrap matching against indexed local issues.\n\t\t\tif bm != nil {\n\t\t\t\tresult := bm.FindMatchIndexed(extIssue, idx)\n\t\t\t\tif result.Matched {\n\t\t\t\t\t// Link the existing local issue to this ADO item.\n\t\t\t\t\tupdates := map[string]interface{}{\n\t\t\t\t\t\t\"external_ref\":  ref,\n\t\t\t\t\t\t\"source_system\": \"ado:\" + extIssue.ID,\n\t\t\t\t\t}\n\t\t\t\t\tif err := store.UpdateIssue(ctx, result.BeadsID, updates, actor); err == nil {\n\t\t\t\t\t\t*matchCount++\n\t\t\t\t\t\tif warn != nil {\n\t\t\t\t\t\t\twarn(fmt.Sprintf(\"Bootstrap matched ADO #%s → %s (%s)\", extIssue.ID, result.BeadsID, result.MatchType))\n\t\t\t\t\t\t}\n\t\t\t\t\t\treturn true // GetIssueByExternalRef will now find it.\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\tif result.Candidates > 1 && warn != nil {\n\t\t\t\t\twarn(fmt.Sprintf(\"Ambiguous bootstrap match for ADO #%s: %d candidates\", extIssue.ID, result.Candidates))\n\t\t\t\t}\n\t\t\t}\n\n\t\t\t// No match found — skip if noCreate, otherwise let engine create.\n\t\t\treturn !noCreate\n\t\t}\n\t}\n\n\treturn hooks\n}\n\n// buildADOPushHooks creates PushHooks for ADO-specific push filtering.\n// When --types or --states are set, local beads are filtered before pushing\n// to ADO by mapping the ADO filter values to beads types/statuses.\n// When noCreate is true, only issues already linked to ADO work items\n// are pushed (no new work items are created).\nfunc buildADOPushHooks(mapper tracker.FieldMapper, isExternalRef func(string) bool, filters *ado.PullFilters, noCreate bool) *tracker.PushHooks {\n\tvar allowedTypes map[types.IssueType]bool","sourceCodeStart":909,"sourceCodeEnd":945,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/cmd/bd/ado.go#L909-L945","documentation":"During ADO bootstrap resolution, when an external ADO issue cannot be uniquely matched to a beads issue, the resolver returns multiple candidates. If result.Candidates > 1, this warning is emitted and the issue is left unmatched so the engine does not guess — a wrong auto-link would corrupt external references.","triggerScenarios":"Multiple beads issues share the same title/identity heuristic used for bootstrap matching (e.g. duplicated issues after a re-import, or two issues created from the same ADO item before external refs existed).","commonSituations":"Re-importing or cloning an issue database creating duplicate beads issues; fuzzy title matching hitting near-identical titles; running bootstrap matching before deduplication cleanup.","solutions":["Find and merge/close the duplicate beads issues so exactly one candidate remains, then re-run sync.","Manually link the ADO item to the correct beads issue (set the external ref) so bootstrap matching is no longer needed.","Tighten matching by ensuring titles/external refs are unique before bootstrap."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// before bootstrap, ensure unique candidates\n// e.g. check for duplicate beads issues sharing titles/external refs\nif dupes := findDuplicateBeadsIssues(extIssue); len(dupes) > 1 {\n\t// resolve duplicates manually first\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Watch for this warning in sync output and dedupe issues promptly.","Set external refs explicitly instead of relying on heuristic title matching.","Run dedup checks after any import/clone of the issue database."],"tags":["azure-devops","bootstrap","matching","ambiguity","warning"],"backgroundTag":"ambiguous-match","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}