unsupported type, expected search.LocalRef or NetworkRef, go

Error message

unsupported type, expected search.LocalRef or NetworkRef, got %T

What it means

When resolving a reference field in a GraphQL Get query, makeResolveRefField expects every item in the stored reference list to be a search.LocalRef or NetworkRef. Any other Go type stored under the reference property (e.g. a raw models.MultipleRef or a plain map without the beacon-decoded wrapper) falls into the default branch and returns this formatted error including the actual Go type via %T.

Source

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

			// unresolved references, this is the case when accepts refs to types
			// ClassA and ClassB and the object only contains refs to one type (e.g.
			// ClassA). Now if the user only asks for resolving all of the other type
			// (i.e. ClassB), then all results would be returned unresolved (as
			// models.MultipleRef).

			return nil, nil
		}
		results := make([]interface{}, len(items))
		for i, item := range items {
			switch v := item.(type) {
			case search.LocalRef:
				// inject some meta data so the ResolveType can determine the type
				localRef := v.Fields
				localRef["__refClassType"] = "local"
				localRef["__refClassName"] = v.Class
				results[i] = localRef
			default:
				return nil, fmt.Errorf("unsupported type, expected search.LocalRef or NetworkRef, got %T", v)
			}
		}
		return results, nil
	}
}

View on GitHub (pinned to 75aa4b6d11)

Solutions

Check the %T part of the message and trace why that type was stored/returned instead of search.LocalRef
Ensure the object extraction path decodes beacons into search.LocalRef / NetworkRef before GraphQL resolution
Re-import or rewrite the affected objects so their reference properties hold valid beacons
Upgrade Weaviate if this occurs after a version migration (related importer bugs were fixed in later releases)

Defensive patterns

Strategy: validation

Validate before calling

// ensure imported objects store proper beacons
for (const ref of obj["hasArticle"] ?? []) {
  if (typeof ref.beacon !== "string") throw new Error("reference must be a beacon object");
}

Type guard

function isLocalRef(v) {
  return v != null && typeof v === "object" && typeof v.class === "string" && typeof v.fields === "object";
}

Try / catch

try {
  result = await client.graphql.get().withClassName('Post').withFields('hasArticle { ... on Article { title } }').do();
} catch (e) {
  if (String(e).includes('unsupported type')) console.error('Corrupt reference payload — re-import affected objects');
  throw e;
}

Prevention

Only write references through supported SDK batch APIs that build beacons
After upgrading Weaviate, run a smoke query on ref properties before bulk imports
Never mutate raw search result items before passing them back into GraphQL resolution
Monitor for importer errors indicating unresolved references

When it happens

Trigger: A stored object's reference property contains values that were not decoded into search.LocalRef (e.g. raw beacon maps returned by an extractor that skipped reference resolution), and the client queried that reference field so the GraphQL layer iterates the items.

Common situations: Internal invariant violations after upgrades or custom extractors/additional-arguments that return unresolved references; clients writing malformed reference payloads that bypass normal deserialization; code changes to search.Result fields.

Related errors

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