{"record":{"id":"57e699e763fc3f9e","repo":"weaviate/weaviate","slug":"local-ref-refers-to-class-s-but-no-such-kind-e","errorCode":null,"errorMessage":"local ref refers to class '%s', but no such kind exists in the peer network","messagePattern":"local ref refers to class '(.+?)', but no such kind exists in the peer network","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"error","filePath":"adapters/handlers/graphql/local/get/class_builder_references.go","lineNumber":76,"sourceCode":"\t})\n\n\treturn &graphql.Field{\n\t\tType:        graphql.NewList(classUnion),\n\t\tDescription: property.Description,\n\t\tResolve:     makeResolveRefField(),\n\t}\n}\n\nfunc makeResolveClassUnionType(knownClasses *map[string]*graphql.Object) graphql.ResolveTypeFn {\n\treturn func(p graphql.ResolveTypeParams) *graphql.Object {\n\t\tvalueMap := p.Value.(map[string]interface{})\n\t\trefType := valueMap[\"__refClassType\"].(string)\n\t\tswitch refType {\n\t\tcase \"local\":\n\t\t\tclassName := valueMap[\"__refClassName\"].(string)\n\t\t\tclassObj, ok := (*knownClasses)[className]\n\t\t\tif !ok {\n\t\t\t\tpanic(fmt.Errorf(\n\t\t\t\t\t\"local ref refers to class '%s', but no such kind exists in the peer network\", className))\n\t\t\t}\n\t\t\treturn classObj\n\t\tdefault:\n\t\t\tpanic(fmt.Sprintf(\"unknown ref type %#v\", refType))\n\t\t}\n\t}\n}\n\nfunc makeResolveRefField() graphql.FieldResolveFn {\n\treturn func(p graphql.ResolveParams) (interface{}, error) {\n\t\tif p.Source.(map[string]interface{})[p.Info.FieldName] == nil {\n\t\t\treturn nil, nil\n\t\t}\n\n\t\titems, ok := p.Source.(map[string]interface{})[p.Info.FieldName].([]interface{})\n\t\tif !ok {\n\t\t\t// could be a models.MultipleRef which would indicate that we found only","sourceCodeStart":58,"sourceCodeEnd":94,"githubUrl":"https://github.com/weaviate/weaviate/blob/75aa4b6d11f8818305aafd4440b4e32794f7ca04/adapters/handlers/graphql/local/get/class_builder_references.go#L58-L94","documentation":"During a GraphQL Local Get with cross-references, Weaviate resolves each returned reference to the GraphQL object type of its target class via makeResolveClassUnionType. The resolver reads the injected __refClassName metadata and looks the class up in the map of known (schema-registered) GraphQL class objects. It panics when the reference points to a class name that is not present in that map, meaning the reference is dangling — the target class does not exist in the (peer network) schema.","triggerScenarios":"A Get query resolves a reference property whose stored beacon points to a class that was deleted from the schema, or whose class name is inconsistent with the property's declared dataType, or (in network/peered setups) whose target class exists only on a peer that is no longer registered. Also triggered if __refClassType was injected as 'local' but the class was pruned from knownClasses during schema build.","commonSituations":"Deleting a collection while objects still hold references to it; renaming a class without migrating old beacons; cluster setups where a peer hosting the target class was removed; stale GraphQL schema cache after concurrent schema changes.","solutions":["Re-create the missing class (or restore it from backup) so the stored beacons resolve again","Find and remove/fix dangling references to the deleted class in remaining objects","Rebuild/refresh the schema so the GraphQL layer picks up all existing classes","If using network refs (deprecated), verify the peers configuration lists the peer hosting the target class"],"exampleFix":"// before: objects reference deleted class 'Article' -> panic\nresult, _ := graphqlClient.Query(\"{ Get { Post { hasArticle { ... on Article { title } } } } }\")\n// after: recreate the class or clean dangling refs first\nschemaManager.AddClass(ctx, principal, articleClass) // restore 'Article'\nresult, _ = graphqlClient.Query(\"{ Get { Post { hasArticle { ... on Article { title } } } } }\")","handlingStrategy":"validation","validationCode":"// before querying refs, confirm the target class exists in the schema\nschema, _ := client.Schema().Getter().Do(ctx)\nhasClass := false\nfor _, c := range schema.Classes {\n  if c.Class == \"Article\" { hasClass = true }\n}\nif !hasClass { /* recreate 'Article' or skip ref fields */ }","typeGuard":"function hasTargetClass(schema, className) {\n  return Array.isArray(schema?.classes) && schema.classes.some(c => c.class === className);\n}","tryCatchPattern":null,"preventionTips":["Do not delete a collection while other objects still reference it — query for dangling refs first","After schema changes, verify the GraphQL schema cache is rebuilt before running ref-heavy queries","In cluster setups, ensure all peers hosting referenced classes are registered before querying","Add integration tests that Get with reference fields after class deletions"],"tags":["graphql","references","schema","dangling-ref"],"backgroundTag":"dangling-reference-target-class-missing","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"}