nearThermal.targetVectors cannot provide more than 1 target

Error message

nearThermal.targetVectors cannot provide more than 1 target vector value

What it means

The nearThermal argument's targetVectors list contains more than one vector name. Because nearThermal performs similarity search against a single media embedding, Weaviate restricts targetVectors to at most one entry when the query targets multi-vector collections. validateNearThermalFn enforces this limit.

Source

Thrown at usecases/modulecomponents/arguments/nearThermal/param.go:58

}

func validateNearThermalFn(param interface{}) error {
	nearThermal, ok := param.(*NearThermalParams)
	if !ok {
		return errors.New("'nearThermal' invalid parameter")
	}

	if len(nearThermal.Thermal) == 0 {
		return errors.New("'nearThermal.thermal' needs to be defined")
	}

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

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

	return nil
}

View on GitHub (pinned to 75aa4b6d11)

Solutions

Reduce targetVectors to a single vector name in the nearThermal argument
Pick the specific named vector the thermal module produces (e.g. the thermal embedding vector) rather than passing all collection vectors
If you need to search multiple vectors, issue one nearThermal query per target vector and combine results client-side
In dynamic query builders, assert len(targetVectors) <= 1 for nearThermal before serializing the request

Example fix

// before
nearThermal: {thermal: "...", targetVectors: ["thermal_vec", "rgb_vec"]}

// after
nearThermal: {thermal: "...", targetVectors: ["thermal_vec"]}

Defensive patterns

Strategy: validation

Validate before calling

if p, ok := arg.(*nearThermal.NearThermalParams); ok && p != nil && len(p.TargetVectors) > 1 {
    return fmt.Errorf("nearThermal supports at most 1 target vector, got %d", len(p.TargetVectors))
}

Try / catch

err := validateNearThermalFn(arg)
if err != nil && strings.Contains(err.Error(), "targetVectors") {
    // truncate to the first vector or fan out one query per vector
}

Prevention

Always pass exactly one target vector for nearThermal queries
In multi-vector collections, name the specific vector the thermal module produced
Add a builder-level assert len(targetVectors) <= 1 for media near* arguments

When it happens

Trigger: Sending nearThermal: {thermal: "...", targetVectors: ["a", "b"]} against a collection with multiple named vectors — the list has length > 1, which the validator rejects.

Common situations: Copy-pasting a nearText-style query where multiple target vectors may be handled differently; generic query builders that forward the whole configured targetVectors array without truncating; schema evolution adding a second named vector to an existing collection that already had a nearThermal query listing all vectors.

Related errors

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