weaviate/weaviate · error

near_object: id is required

Error message

near_object: id is required

What it means

The gRPC Aggregate request contained a near_object search clause without an object id. Weaviate requires the id to resolve the object's vector before performing the near-object aggregation, so the parse layer rejects the request before any search runs. This mirrors the same validation in the GraphQL API layer.

Source

Thrown at adapters/handlers/grpc/v1/parse_aggregate_request.go:131

			// also part of the GraphQL API, so we need to duplicate it in order to get
			// the same behavior
			if nv.Distance != nil && nv.Certainty != nil {
				return nil, fmt.Errorf("near_vector: cannot provide distance and certainty")
			}

			if nv.Certainty != nil {
				params.NearVector.Certainty = *nv.Certainty
			}

			if nv.Distance != nil {
				params.NearVector.Distance = *nv.Distance
				params.NearVector.WithDistance = true
			}
		}
	case *pb.AggregateRequest_NearObject:
		if no := search.NearObject; no != nil {
			if no.Id == "" {
				return nil, fmt.Errorf("near_object: id is required")
			}
			params.NearObject = &searchparams.NearObject{
				ID:            no.Id,
				TargetVectors: targetVectors,
			}

			// The following business logic should not sit in the API. However, it is
			// also part of the GraphQL API, so we need to duplicate it in order to get
			// the same behavior
			if no.Distance != nil && no.Certainty != nil {
				return nil, fmt.Errorf("near_object: cannot provide distance and certainty")
			}

			if no.Certainty != nil {
				params.NearObject.Certainty = *no.Certainty
			}

			if no.Distance != nil {

View on GitHub (pinned to 75aa4b6d11)

Solutions

1. Set the Id field on the NearObject message before sending the Aggregate request.
2. In the client, fail fast when the source object id is missing instead of sending the request.
3. If you only need vector-similarity, switch to near_vector with an explicit vector.

Example fix

// before
search := &pb.AggregateRequest_NearObject{NearObject: &pb.NearObject{}}
// after
search := &pb.AggregateRequest_NearObject{NearObject: &pb.NearObject{Id: "some-uuid"}}

if req.GetNearObject() != nil && req.GetNearObject().GetId() == "" {
    return errors.New("near_object: id is required")
}

func hasValidNearObjectId(no *pb.NearObject) bool {
    return no != nil && no.Id != ""
}

When it happens

Trigger: Sending a pb.AggregateRequest with Search set to NearObject whose Id field is the empty string (field left unset in the client or proto zero value).

Common situations: Client code builds the NearObject message but forgets to assign Id (e.g. passing a struct with a nil/empty id because the lookup failed upstream, or a dynamic id variable that was empty).

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• near_object: cannot provide distance and certainty
• near_object: id is required
• near_object: cannot provide distance and certainty
• empty id and beacon
• could not find class %s in schema

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