weaviate/weaviate · error

invalid ref type. Needs to be []map, got %T

Error message

invalid ref type. Needs to be []map, got %T

What it means

The whole reference property value matched neither map nor []interface{} in cRef's type switch default — e.g. a plain string, number, or null was sent for a cref property. A terminal shape guard: no ref structure to validate at all.

Source

Thrown at usecases/objects/validation/properties_validation.go:390

		crefs := models.MultipleRef{}
		for _, ref := range refValue {
			refTyped, ok := ref.(map[string]interface{})
			if !ok {
				return nil, fmt.Errorf("multiple references in %s.%s should be a list of maps, but we got: %T",
					className, propertyName, ref)
			}

			cref, err := v.parseAndValidateSingleRef(ctx, propertyName, refTyped, className, tenant)
			if err != nil {
				return nil, err
			}

			crefs = append(crefs, cref)
		}

		return crefs, nil
	default:
		return nil, fmt.Errorf("invalid ref type. Needs to be []map, got %T", pv)
	}
}

func stringVal(val interface{}) (string, error) {
	typed, ok := val.(string)
	if !ok {
		return "", fmt.Errorf("not a string, but %T", val)
	}

	return typed, nil
}

func boolVal(val interface{}) (bool, error) {
	typed, ok := val.(bool)
	if !ok {
		return false, fmt.Errorf("not a bool, but %T", val)
	}

View on GitHub (pinned to 75aa4b6d11)

Solutions

1. Send references as an array of {"beacon": ...} objects.
2. Do not send bare beacon strings or UUIDs for cref properties.
3. Check for null/undefined creeping into ref fields from client code.

When it happens

Trigger: Thrown at usecases/objects/validation/properties_validation.go:390 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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