weaviate/weaviate · error

parse refs for prop %q

Error message

parse refs for prop %q

What it means

parseSchema walks an object's properties and, for each selected reference property, calls parseRefs to resolve its references. A failure for property propName is wrapped with "parse refs for prop %q", naming the exact property whose references could not be resolved. Called from parseObject, parseAdditionalGroup, and resolveRef.

Source

Thrown at adapters/repos/db/refcache/resolver.go:142

func (r *Resolver) parseSchema(schema map[string]interface{},
	idx search.SelectPropertiesIndex,
) (map[string]interface{}, error) {
	for propName, value := range schema {
		refs, ok := value.(models.MultipleRef)
		if !ok {
			// not a ref, not interesting for us
			continue
		}

		selectProp := idx.Find(propName)
		if selectProp == nil {
			// user is not interested in this prop
			continue
		}

		parsed, err := r.parseRefs(refs, propName, *selectProp)
		if err != nil {
			return schema, errors.Wrapf(err, "parse refs for prop %q", propName)
		}

		if parsed != nil {
			schema[propName] = parsed
		}
	}

	return schema, nil
}

func (r *Resolver) parseRefs(input models.MultipleRef, prop string,
	selectProp search.SelectProperty,
) ([]interface{}, error) {
	var refs []interface{}
	for _, selectPropRef := range selectProp.Refs {
		// built once, reused for every ref of this property
		innerIdx := selectPropRef.RefProperties.Indexed()
		additionalProperties := selectPropRef.AdditionalProperties

View on GitHub (pinned to 75aa4b6d11)

Solutions

1. Fix the named property in the error — check which classes it references in the schema
2. Verify all referenced classes still exist and match the property definition
3. Inspect the inner wrapped error for the per-item position detail
4. Clean up inconsistent refs on affected objects

// Confirm the property's reference classes exist before resolving
prop := classProperty(schema, className, propName)
for _, dt := range prop.DataType {
    refClass := strings.TrimPrefix(strings.TrimSuffix(dt, ">"), "<")
    if !classExists(schema, refClass) {
        return fmt.Errorf("property %q references missing class %q", propName, refClass)
    }
}

// Go
func isPropParseError(err error, prop string) bool {
    return err != nil && strings.Contains(err.Error(), fmt.Sprintf("parse refs for prop %q", prop))
}

// Go
if err != nil {
    if isPropParseError(err, "hasAuthor") {
        log.Warnf("bad refs on hasAuthor, querying without it: %v", err)
        return queryWithoutProperty(ctx, "hasAuthor")
    }
    return err
}

When it happens

Trigger: Reference resolution fails for a specific property — nested resolveRefs error (e.g. inner per-item failure), malformed select property, or refs pointing to a class that no longer matches the property's class list.

Common situations: Schema drift: property defined with class X but data contains refs to class Y; querying a property whose referenced class was renamed or deleted; nested GraphQL ref selections with inner failures.

Related errors

• fetch job list
• build nested cache
• build reference cache
• parse at position %d
• resolve ref

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