weaviate/weaviate · error

failed to parse beacon %q: %w

Error message

failed to parse beacon %q: %w

What it means

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.

Source

Thrown at usecases/traverser/grouper/merge_group.go:303

					"element %d: expected reference values to be slice, but got %T", i, elem)
			}

			if err := parseRefTypeInterfaceSlice(asSlice, &out, seenID); err != nil {
				return nil, fmt.Errorf("element %d: %w", i, err)
			}
		}
	}

	return out, nil
}

func parseRefTypeMultipleRef(refs models.MultipleRef,
	returnRefs *[]interface{}, seenIDs map[string]struct{},
) error {
	for _, singleRef := range refs {
		parsed, err := crossref.Parse(singleRef.Beacon.String())
		if err != nil {
			return fmt.Errorf("failed to parse beacon %q: %w", singleRef.Beacon.String(), err)
		}
		idString := parsed.TargetID.String()
		if _, ok := seenIDs[idString]; ok {
			// duplicate
			continue
		}

		*returnRefs = append(*returnRefs, singleRef)
		seenIDs[idString] = struct{}{} // make sure we skip this next time
	}
	return nil
}

func parseRefTypeInterfaceSlice(refs []interface{},
	returnRefs *[]interface{}, seenIDs map[string]struct{},
) error {
	for _, singleRef := range refs {
		asRef, ok := singleRef.(search.LocalRef)

View on GitHub (pinned to 75aa4b6d11)

Solutions

1. Read the quoted beacon in the error to see the exact malformed value
2. Fix the stored reference by re-linking with a valid UUID beacon (PATCH or batch references)
3. Validate UUIDs client-side before writing references (e.g. uuid.Parse)
4. If migrating between instances, regenerate beacons with the target instance's class and IDs

Example fix

// before
models.MultipleRef{{Beacon: &b}} where b = "weaviate://Article/not-a-uuid"
// after
b = "weaviate://Article/2b4a5c6d-1e2f-4a3b-8c9d-0f1e2d3c4b5a"

// Mirror of crossref.Parse: validate beacon before storing
function validateBeacon(beacon) {
  const u = new URL(beacon)
  if (u.protocol !== 'weaviate:') throw new Error(`bad scheme: ${beacon}`)
  const parts = u.pathname.split('/').filter(Boolean)
  const uuid = parts[parts.length - 1]
  const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
  if (!UUID.test(uuid)) throw new Error(`bad target id in ${beacon}`)
  return beacon
}

try {
  const res = await client.graphql.get().withGroupBy({path: ['publishedIn']})
} catch (e) {
  const m = /failed to parse beacon "([^"]+)"/.exec(e.message)
  if (m) console.error('Fix stored reference beacon:', m[1])
  else throw e
}

When it happens

Trigger: 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).

Common situations: 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.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• element %d: %w
• element %d: expected reference values to be slice, but got %
• no groupBy must be a list, instead got: %#v
• missing groupedBy on group %d of aggregate result
• grouping by cross-refs not supported

AI-assisted analysis of weaviate/weaviate@75aa4b6d11 (2026-09-04). Data as JSON: /api/errors/2911f5c16da9c8c3. Report an issue: GitHub.