cannot combine nearVector and vector in hybrid search

Error message

cannot combine nearVector and vector in hybrid search

What it means

The parser rejects hybrid search requests that set both NearVectorParams and an explicit Vector field, since both specify the query vector directly. Only one explicit vector source may be provided per hybrid search.

Source

Thrown at adapters/handlers/grpc/v1/parse_search_request.go:438

	if req.GroupBy != nil {
		groupBy, err := extractGroupBy(req.GroupBy, &out, class)
		if err != nil {
			return dto.GetParams{}, err
		}
		out.AdditionalProperties.Group = true

		out.GroupBy = groupBy
	}

	if out.HybridSearch != nil && out.HybridSearch.NearTextParams != nil && out.HybridSearch.NearVectorParams != nil {
		return dto.GetParams{}, errors.New("cannot combine nearText and nearVector in hybrid search")
	}
	if out.HybridSearch != nil && out.HybridSearch.NearTextParams != nil && out.HybridSearch.Vector != nil {
		return dto.GetParams{}, errors.New("cannot combine nearText and query in hybrid search")
	}
	if out.HybridSearch != nil && out.HybridSearch.NearVectorParams != nil && out.HybridSearch.Vector != nil {
		return dto.GetParams{}, errors.New("cannot combine nearVector and vector in hybrid search")
	}
	if out.Selection != nil {
		if mmr := out.Selection.MMR; mmr != nil {
			if mmr.Limit == 0 {
				return dto.GetParams{}, errors.New("MMR limit must be at least 1")
			}
			if out.Pagination.Limit > 0 && int(mmr.Limit) > out.Pagination.Limit {
				return dto.GetParams{}, fmt.Errorf("MMR limit (%d) cannot be larger than the query limit (%d)", mmr.Limit, out.Pagination.Limit)
			}
			if mmr.Balance < 0 || mmr.Balance > 1 {
				return dto.GetParams{}, errors.New("MMR balance must be between 0 and 1")
			}
		}
		selectionTargets := targetVectors
		if len(selectionTargets) == 0 {
			selectionTargets = []string{""}
		}
		for _, tv := range selectionTargets {

View on GitHub (pinned to 75aa4b6d11)

Solutions

Keep only one of nearVector params or the explicit vector field in the hybrid search request
If explicit vectors are desired, drop the nearVector params and set Vector directly (or vice versa)
Audit client request builders to ensure mutually exclusive fields are never populated together

Example fix

// before
hybrid := &pb.Hybrid{
  Vector: vec,
  NearVectorParams: &pb.HybridNearVector{Vector: vec},
}
// after
hybrid := &pb.Hybrid{
  NearVectorParams: &pb.HybridNearVector{Vector: vec},
}

Defensive patterns

Strategy: validation

Validate before calling

func validateHybridVec(h *pb.Hybrid) error {
  if h == nil { return nil }
  if h.NearVectorParams != nil && h.Vector != nil {
    return errors.New("set only one of nearVector or vector in hybrid search")
  }
  return nil
}

Prevention

Use one canonical way to pass explicit vectors (prefer the vector field or nearVector, not both)
Add unit tests for request builders asserting mutual exclusivity

When it happens

Trigger: Hybrid search where HybridSearch.NearVectorParams != nil and HybridSearch.Vector != nil at the same time, e.g. client populates both nearVector.vector and the top-level vector field of the hybrid search message.

Common situations: Duplicated vector input after API upgrades where both fields exist; helper libraries that set the vector field as a default while also building nearVector params; copy-pasted request-building code.

Related errors

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