local ref refers to class '%s', but no such kind exists in t

Error message

local ref refers to class '%s', but no such kind exists in the peer network

What it means

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.

Source

Thrown at adapters/handlers/graphql/local/get/class_builder_references.go:76

	})

	return &graphql.Field{
		Type:        graphql.NewList(classUnion),
		Description: property.Description,
		Resolve:     makeResolveRefField(),
	}
}

func makeResolveClassUnionType(knownClasses *map[string]*graphql.Object) graphql.ResolveTypeFn {
	return func(p graphql.ResolveTypeParams) *graphql.Object {
		valueMap := p.Value.(map[string]interface{})
		refType := valueMap["__refClassType"].(string)
		switch refType {
		case "local":
			className := valueMap["__refClassName"].(string)
			classObj, ok := (*knownClasses)[className]
			if !ok {
				panic(fmt.Errorf(
					"local ref refers to class '%s', but no such kind exists in the peer network", className))
			}
			return classObj
		default:
			panic(fmt.Sprintf("unknown ref type %#v", refType))
		}
	}
}

func makeResolveRefField() graphql.FieldResolveFn {
	return func(p graphql.ResolveParams) (interface{}, error) {
		if p.Source.(map[string]interface{})[p.Info.FieldName] == nil {
			return nil, nil
		}

		items, ok := p.Source.(map[string]interface{})[p.Info.FieldName].([]interface{})
		if !ok {
			// could be a models.MultipleRef which would indicate that we found only

View on GitHub (pinned to 75aa4b6d11)

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

Example fix

// before: objects reference deleted class 'Article' -> panic
result, _ := graphqlClient.Query("{ Get { Post { hasArticle { ... on Article { title } } } } }")
// after: recreate the class or clean dangling refs first
schemaManager.AddClass(ctx, principal, articleClass) // restore 'Article'
result, _ = graphqlClient.Query("{ Get { Post { hasArticle { ... on Article { title } } } } }")

Defensive patterns

Strategy: validation

Validate before calling

// before querying refs, confirm the target class exists in the schema
schema, _ := client.Schema().Getter().Do(ctx)
hasClass := false
for _, c := range schema.Classes {
  if c.Class == "Article" { hasClass = true }
}
if !hasClass { /* recreate 'Article' or skip ref fields */ }

Type guard

function hasTargetClass(schema, className) {
  return Array.isArray(schema?.classes) && schema.classes.some(c => c.class === className);
}

Prevention

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

When it happens

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

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

Related errors

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