weaviate/weaviate · error

invalid 'where' filter

Error message

invalid 'where' filter

What it means

Weaviate wraps any failure from validateFilters during an aggregation with "invalid 'where' filter". Filter validation runs before execution because where-filters can reference other collections, and each referenced collection must exist and be readable by the authenticated principal (filters.ValidateFilters authorizes and resolves classes via the schema getter). The wrapped inner error names the actual cause (unknown class/property, bad operator, or permission denial).

Source

Thrown at usecases/traverser/traverser_aggregate.go:39

	"github.com/weaviate/weaviate/entities/models"
	"github.com/weaviate/weaviate/entities/schema"
	"github.com/weaviate/weaviate/usecases/modules"
)

// Aggregate resolves meta queries
func (t *Traverser) Aggregate(ctx context.Context, principal *models.Principal, params *aggregation.Params) (any, error) {
	// TODO(dyma): if the collection is referenced by its alias, the metric may underestimate the true number of queries.
	// Do we want to resolve the alias before recording this query?
	t.metrics.QueriesAggregateInc(params.ClassName.String())
	defer t.metrics.QueriesAggregateDec(params.ClassName.String())

	if cls := t.schemaGetter.ResolveAlias(params.ClassName.String()); cls != "" {
		params.ClassName = schema.ClassName(cls)
	}

	// validate here, because filters can contain references that need to be authorized
	if err := t.validateFilters(ctx, principal, params.Filters); err != nil {
		return nil, errors.Wrap(err, "invalid 'where' filter")
	}

	if params.NearVector != nil || params.NearObject != nil || len(params.ModuleParams) > 0 {
		className := params.ClassName.String()
		err := t.nearParamsVector.validateNearParams(params.NearVector,
			params.NearObject, params.ModuleParams, className)
		if err != nil {
			return nil, err
		}
		targetVectors, err := t.nearParamsVector.targetFromParams(ctx,
			params.NearVector, params.NearObject, params.ModuleParams, className, params.Tenant)
		if err != nil {
			return nil, err
		}

		targetVectors, err = t.targetVectorParamHelper.GetTargetVectorOrDefault(t.schemaGetter.ReadOnlyClass,
			className, targetVectors)
		if err != nil {

View on GitHub (pinned to 75aa4b6d11)

Solutions

1. Read the inner (wrapped) error to identify which filter operand failed
2. Verify every class and property name in the where filter against the live schema (GET /v1/schema)
3. Ensure the authenticated user/key has read permission on all collections referenced by the filter
4. Rebuild the filter using the current client SDK so operators match property data types

Example fix

// before: filter references deleted class
{"where": {"path": ["hasArticle", "Article", "title"], "operator": "Equal", "valueText": "x"}}
// after: check schema first, use existing class
// GET /v1/schema -> if 'Article' was renamed to 'Post':
{"where": {"path": ["hasArticle", "Post", "title"], "operator": "Equal", "valueText": "x"}}

// Go: verify filter paths against schema before calling Aggregate
schema, _ := client.Schema().Getter().Do(ctx)
known := map[string]bool{}
for _, c := range schema { known[string(c.Class)] = true }
for _, p := range filter.Operands() {
    // ensure every class in nested ref paths exists
    if !known[p.On.Class] { return fmt.Errorf("unknown class %q in filter", p.On.Class) }
}

func classExists(name string, schema []*models.Class) bool {
  for _, c := range schema { if string(c.Class) == name { return true } }
  return false
}

When it happens

Trigger: Calling the Aggregate API (GraphQL aggregate or REST /v1/graphql aggregate) with a where filter whose operand references a nonexistent class or property, uses an operator invalid for the property's data type, or targets a collection the principal is not authorized to read (multi-tenancy/RBAC).

Common situations: Typos in collection names in cross-reference filters; renaming or deleting a class that a saved query still filters on; RBAC users lacking READ on CollectionsMetadata for a referenced class; filters built client-side against an outdated schema.

Related errors

• invalid 'where' filter
• no path found in clause: %v
• due to GraphQL introspection, this role must have the permis
• insufficient permissions to view role
• role grants a permission you do not hold

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