{"record":{"id":"be7cb45bc26bf0cc","repo":"weaviate/weaviate","slug":"target-is-a-single-target-reference-need-multi-ta","errorCode":null,"errorMessage":"target is a single-target reference, need multi-target %v","messagePattern":"target is a single-target reference, need multi-target (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"adapters/handlers/grpc/v1/batch/parse.go","lineNumber":170,"sourceCode":"\t\ttoClass := namespacing.StripQualification(prop.DataType[0])\n\t\tbeacons := make([]interface{}, len(refSingle.Uuids))\n\t\tfor j, uuid := range refSingle.Uuids {\n\t\t\tbeacons[j] = map[string]interface{}{\"beacon\": BEACON_START + toClass + \"/\" + uuid}\n\t\t}\n\t\tprops[propName] = beacons\n\t}\n\treturn nil\n}\n\nfunc extractMultiRefTarget(class *models.Class, properties []*pb.BatchObject_MultiTargetRefProps, props map[string]interface{}, principal *models.Principal, namespacesEnabled bool) error {\n\tfor _, refMulti := range properties {\n\t\tpropName := refMulti.GetPropName()\n\t\tprop, err := schema.GetPropertyByName(class, propName)\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\t\tif len(prop.DataType) < 2 {\n\t\t\treturn fmt.Errorf(\"target is a single-target reference, need multi-target %v\", prop.DataType)\n\t\t}\n\t\t// TargetCollection is user-supplied; route through QualifyRefTarget\n\t\t// for cross-NS policy + storage-shape rule.\n\t\ttargetCollection := schema.UppercaseClassName(refMulti.TargetCollection)\n\t\t_, shortTarget, err := namespacing.QualifyRefTarget(principal, namespacesEnabled, class.Class, targetCollection)\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\t\tbeacons := make([]interface{}, len(refMulti.Uuids))\n\t\tfor j, uid := range refMulti.Uuids {\n\t\t\tbeacons[j] = map[string]interface{}{\"beacon\": BEACON_START + shortTarget + \"/\" + uid}\n\t\t}\n\t\tif props[propName] == nil {\n\t\t\tprops[propName] = beacons\n\t\t} else {\n\t\t\tprops[propName] = append(props[propName].([]interface{}), beacons...)\n\t\t}\n\t}","sourceCodeStart":152,"sourceCodeEnd":188,"githubUrl":"https://github.com/weaviate/weaviate/blob/75aa4b6d11f8818305aafd4440b4e32794f7ca04/adapters/handlers/grpc/v1/batch/parse.go#L152-L188","documentation":"extractMultiRefTarget handles pb reference properties of the multi-target kind. If the property's schema declares fewer than two data types — i.e. it is a plain single-target reference — the multi-target path is invalid and this error is returned listing the property's single data type. The target collection is qualified via namespacing rules before being used for the beacon.","triggerScenarios":"Sending a pb.BatchObject with refs_multi (target_collection set) for a property declared as a single-target reference (one dataType).","commonSituations":"Client SDK version older than multi-target support sending everything as multi-target; payload reuse across collections; property redefined as single-target after being multi-target while clients still send the multi-target shape.","solutions":["Send the reference via refs_single instead of refs_multi","Inspect the schema: if the property should be multi-target, recreate it with an array of target classes","Remove target_collection from the request and align with the single-target property","Align the client SDK with the current schema definition"],"exampleFix":"// before: property 'hasAuthor' is single-target [\"Author\"]\nrefs_multi: [{prop_name: \"hasAuthor\", target_collection: \"Author\", uuids: [\"...\"]}]\n// after\nrefs_single: [{prop_name: \"hasAuthor\", uuids: [\"...\"]}]","handlingStrategy":"validation","validationCode":"const prop = schema.classes.find(c => c.class === 'Post').properties.find(p => p.name === 'hasAuthor');\nif (Array.isArray(prop.dataTypes) && prop.dataTypes.length === 1) {\n  // must use single-target reference shape (refs_single)\n}","typeGuard":"function isSingleTargetProperty(prop) {\n  return Array.isArray(prop?.dataTypes) && prop.dataTypes.length === 1;\n}","tryCatchPattern":"resp, err := client.BatchObjects(ctx, req)\nif err != nil && strings.Contains(err.Error(), \"single-target reference\") {\n  return fmt.Errorf(\"rebuild request using the single-target (refs_single) reference shape: %w\", err)\n}","preventionTips":["Check the property definition (number of dataTypes) before sending references","After migrating a multi-target property back to single-target, update all writers","Use generated SDK types that encode the reference arity","Test batch payloads against a schema snapshot in CI"],"tags":["grpc","batch","references","schema-validation"],"backgroundTag":"reference-target-mismatch","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"}