weaviate/weaviate · error

failed to unmarshal filters: %w

Error message

failed to unmarshal filters: %w

What it means

Returned when the JSON re-encoded filter cannot be unmarshaled into models.WhereFilter — i.e. the filter object's shape does not match the WhereFilter schema (wrong field names/types, e.g. value given as wrong type, or nested structure invalid).

Source

Thrown at adapters/handlers/mcp/search/hybrid.go:110

	var pagination *filters.Pagination
	if args.Limit != nil {
		pagination = &filters.Pagination{
			Limit: *args.Limit,
		}
	}

	// Parse filters if provided
	var localFilter *filters.LocalFilter
	if args.Filters != nil {
		// Convert map to WhereFilter
		filterJSON, err := json.Marshal(args.Filters)
		if err != nil {
			return nil, fmt.Errorf("failed to marshal filters: %w", err)
		}

		var whereFilter models.WhereFilter
		if err := json.Unmarshal(filterJSON, &whereFilter); err != nil {
			return nil, fmt.Errorf("failed to unmarshal filters: %w", err)
		}

		localFilter, err = filterext.Parse(&whereFilter, args.CollectionName, s.namespacesEnabled, principal)
		if err != nil {
			return nil, fmt.Errorf("failed to parse filters: %w", err)
		}
	}

	res, err := s.traverser.GetClass(ctx, principal, dto.GetParams{
		ClassName:            args.CollectionName,
		Tenant:               args.TenantName,
		Properties:           selectProps,
		HybridSearch:         hybridSearch,
		Pagination:           pagination,
		Filters:              localFilter,
		AdditionalProperties: additionalProps,
	})
	if err != nil {

View on GitHub (pinned to 75aa4b6d11)

Solutions

1. Match the models.WhereFilter schema exactly: path, operator (e.g. Equal, And, Or), value* fields with correct types
2. Validate the filter JSON against the WhereFilter schema before calling
3. Use the same filter shape as the REST API /v1/graphql where filter
4. For combinators, nest properly under AND/OR/NOT keys with arrays of filters

Example fix

// before
{"field": "status", "equals": "active"}
// after
{"path": ["status"], "operator": "Equal", "valueText": "active"}

// Go: round-trip the filter into models.WhereFilter before calling
var wf models.WhereFilter
b, _ := json.Marshal(rawFilters)
if err := json.Unmarshal(b, &wf); err != nil {
	return fmt.Errorf("filter does not match WhereFilter schema: %v", err)
}

func isWhereFilterShape(v map[string]any) bool {
	_, hasPath := v["path"]
	_, hasOp := v["operator"]
	return hasPath && hasOp
}

res, err := tool.Hybrid(ctx, args)
if err != nil && strings.Contains(err.Error(), "failed to unmarshal filters") {
	// invalid filter shape: correct to path/operator/value* form, no retry
	return fmt.Errorf("malformed filter: %v", err)
}

When it happens

Trigger: Hybrid called with a filters object whose keys/types don't fit models.WhereFilter: unknown fields with incompatible types, 'value' of a type json cannot target, nested AND/OR filters malformed, or operators given in an invalid structure.

Common situations: LLM/MCP clients composing filters with invented field names; passing filter strings instead of objects; mixing GraphQL-style filter shapes with REST WhereFilter shape; wrong value type (string vs number).

Related errors

• failed to marshal filters: %w
• failed to parse filters: %w
• empty where
• unmarshal response: %w
• unmarshal can-commit response: %w

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