{"record":{"id":"2911f5c16da9c8c3","repo":"weaviate/weaviate","slug":"failed-to-parse-beacon-q-w","errorCode":null,"errorMessage":"failed to parse beacon %q: %w","messagePattern":"failed to parse beacon %q: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"usecases/traverser/grouper/merge_group.go","lineNumber":303,"sourceCode":"\t\t\t\t\t\"element %d: expected reference values to be slice, but got %T\", i, elem)\n\t\t\t}\n\n\t\t\tif err := parseRefTypeInterfaceSlice(asSlice, &out, seenID); err != nil {\n\t\t\t\treturn nil, fmt.Errorf(\"element %d: %w\", i, err)\n\t\t\t}\n\t\t}\n\t}\n\n\treturn out, nil\n}\n\nfunc parseRefTypeMultipleRef(refs models.MultipleRef,\n\treturnRefs *[]interface{}, seenIDs map[string]struct{},\n) error {\n\tfor _, singleRef := range refs {\n\t\tparsed, err := crossref.Parse(singleRef.Beacon.String())\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"failed to parse beacon %q: %w\", singleRef.Beacon.String(), err)\n\t\t}\n\t\tidString := parsed.TargetID.String()\n\t\tif _, ok := seenIDs[idString]; ok {\n\t\t\t// duplicate\n\t\t\tcontinue\n\t\t}\n\n\t\t*returnRefs = append(*returnRefs, singleRef)\n\t\tseenIDs[idString] = struct{}{} // make sure we skip this next time\n\t}\n\treturn nil\n}\n\nfunc parseRefTypeInterfaceSlice(refs []interface{},\n\treturnRefs *[]interface{}, seenIDs map[string]struct{},\n) error {\n\tfor _, singleRef := range refs {\n\t\tasRef, ok := singleRef.(search.LocalRef)","sourceCodeStart":285,"sourceCodeEnd":321,"githubUrl":"https://github.com/weaviate/weaviate/blob/75aa4b6d11f8818305aafd4440b4e32794f7ca04/usecases/traverser/grouper/merge_group.go#L285-L321","documentation":"parseRefTypeMultipleRef walks a models.MultipleRef and parses each beacon string with the crossref package to extract the target UUID. Any beacon that fails parsing aborts with \"failed to parse beacon \\\"<raw>\\\": <cause>\". Beacons must follow the canonical weaviate://<peer>/<collection>/<uuid> form.","triggerScenarios":"A groupBy query over a reference property where a stored MultipleRef contains a beacon string that is not a valid URL or whose target ID is not a valid UUID (e.g. written by an old client or hand-edited export).","commonSituations":"Data imported from JSON dumps with symbolic names instead of UUIDs, cross-instance restores where the peer prefix is stale, or clients building beacons by string concatenation.","solutions":["Read the quoted beacon in the error to see the exact malformed value","Fix the stored reference by re-linking with a valid UUID beacon (PATCH or batch references)","Validate UUIDs client-side before writing references (e.g. uuid.Parse)","If migrating between instances, regenerate beacons with the target instance's class and IDs"],"exampleFix":"// before\nmodels.MultipleRef{{Beacon: &b}} where b = \"weaviate://Article/not-a-uuid\"\n// after\nb = \"weaviate://Article/2b4a5c6d-1e2f-4a3b-8c9d-0f1e2d3c4b5a\"","handlingStrategy":"validation","validationCode":"// Mirror of crossref.Parse: validate beacon before storing\nfunction validateBeacon(beacon) {\n  const u = new URL(beacon)\n  if (u.protocol !== 'weaviate:') throw new Error(`bad scheme: ${beacon}`)\n  const parts = u.pathname.split('/').filter(Boolean)\n  const uuid = parts[parts.length - 1]\n  const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i\n  if (!UUID.test(uuid)) throw new Error(`bad target id in ${beacon}`)\n  return beacon\n}","typeGuard":null,"tryCatchPattern":"try {\n  const res = await client.graphql.get().withGroupBy({path: ['publishedIn']})\n} catch (e) {\n  const m = /failed to parse beacon \"([^\"]+)\"/.exec(e.message)\n  if (m) console.error('Fix stored reference beacon:', m[1])\n  else throw e\n}","preventionTips":["Never build beacons via string concatenation of human-readable names","Use uuidv4 generation and validate with a UUID parser before writing refs","After exports/imports between instances, audit beacon peer prefixes","The quoted beacon in the error identifies the exact object to repair"],"tags":["graphql","groupby","reference","beacon","uuid"],"backgroundTag":"invalid-beacon-reference","analyzedSha":"75aa4b6d11f8818305aafd4440b4e32794f7ca04","analyzedAt":"2026-09-04T14:58:20.392Z","contentChangedAt":"2026-09-04T14:58:20.392Z","schemaVersion":2},"datasetVersion":"2026-09-11T21:17:09.523Z"}