weaviate/weaviate · error

nearIMU cannot provide both distance and certainty

Error message

nearIMU cannot provide both distance and certainty

What it means

nearIMU, like all near* clauses, permits either certainty or distance as the relevance bound but not both. validateNearIMUFn returns this error when Certainty is non-zero while WithDistance is true. The two settings would contradict each other in threshold computation, so the request is rejected.

Source

Thrown at usecases/modulecomponents/arguments/nearImu/param.go:53

	return n.Certainty != 0 || n.WithDistance
}

func (n NearIMUParams) GetTargetVectors() []string {
	return n.TargetVectors
}

func validateNearIMUFn(param interface{}) error {
	nearIMU, ok := param.(*NearIMUParams)
	if !ok {
		return errors.New("'nearIMU' invalid parameter")
	}

	if len(nearIMU.IMU) == 0 {
		return errors.New("'nearIMU.imu' needs to be defined")
	}

	if nearIMU.Certainty != 0 && nearIMU.WithDistance {
		return errors.New(
			"nearIMU cannot provide both distance and certainty")
	}

	if len(nearIMU.TargetVectors) > 1 {
		return errors.New(
			"nearIMU.targetVectors cannot provide more than 1 target vector value")
	}

	return nil
}

View on GitHub (pinned to 75aa4b6d11)

Solutions

1. Keep only one of certainty or distance in the nearIMU clause
2. Set the other field explicitly to zero/omitted in your query builder
3. If you need layered thresholds, do one in-query and one post-filter client-side

Example fix

// before
nearIMU: { imu: "...", certainty: 0.75, distance: 0.2 }
// after
nearIMU: { imu: "...", distance: 0.2 }

if (args.nearIMU?.certainty != null && args.nearIMU?.distance != null) {
  throw new Error("nearIMU: provide certainty or distance, not both");
}

function hasExactlyOneBound(clause) {
  return ["certainty", "distance"].filter(k => clause[k] != null).length === 1;
}

When it happens

Trigger: A nearIMU clause specifying both certainty (e.g. 0.75) and distance (which sets WithDistance) — detected by nearIMU.Certainty != 0 && nearIMU.WithDistance.

Common situations: Query templates merging certainty and distance semantics; migration from distance-based to certainty-based searches leaving stale fields; automated clients always emitting both optional params.

Related errors

• nearAudio cannot provide both distance and certainty
• nearDepth cannot provide both distance and certainty
• 'nearIMU.imu' needs to be defined
• nearIMU.targetVectors cannot provide more than 1 target vect
• nearImage cannot provide both distance and certainty

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