alibaba/spring-ai-alibaba · error · IllegalArgumentException

hybrid alpha should be between 0 ~ 1.

Error message

hybrid alpha should be between 0 ~ 1.

What it means

searchByHybrid validates that the SearchRequest hybridWeight (the alpha balancing semantic vs full-text scoring) lies within [0,1]; outside that range it throws IllegalArgumentException("hybrid alpha should be between 0 ~ 1."). A hybrid search with an out-of-range alpha is meaningless and rejected up front.

Solutions

1. Clamp hybridWeight to [0,1] before building the SearchRequest.
2. Convert percentage inputs: use 0.5 instead of 50.
3. Validate user-supplied config values at load time and reject out-of-range alphas early.
4. Use 0.0 for pure full-text and 1.0 for pure semantic if you intended an extreme.

Example fix

// before
SearchRequest req = SearchRequest.builder().query("q")
    .searchType(SearchType.HYBRID).hybridWeight(50).build(); // throws
// after
double alpha = Math.max(0.0, Math.min(1.0, config.getHybridAlpha()));
SearchRequest req = SearchRequest.builder().query("q")
    .searchType(SearchType.HYBRID).hybridWeight(alpha).build();

// Java
double w = searchRequest.getHybridWeight();
if (w < 0.0 || w > 1.0) throw new IllegalArgumentException("hybridWeight must be within [0,1], got " + w);

static double clampHybridWeight(Double w) {
    if (w == null) return 0.5; // sensible default
    return Math.max(0.0, Math.min(1.0, w));
}

try { return vectorStore.similaritySearch(request); } catch (IllegalArgumentException e) {
    if (e.getMessage().contains("hybrid alpha")) {
        SearchRequest fixed = request.mutate().hybridWeight(clampHybridWeight(request.getHybridWeight())).build();
        return vectorStore.similaritySearch(fixed);
    }
    throw e;
}

When it happens

Trigger: Calling VectorStore.similaritySearch with searchType=HYBRID and SearchRequest.builder().hybridWeight(x) where x < 0 or x > 1 (e.g. passing a percentage like 50 instead of 0.5).

Common situations: Confusing percentage (0–100) with fraction (0–1) when setting hybrid weight; inverting the weight (1 - weight); copying a weight from a different library that uses a different scale.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• Delete operation failed
• Elastic search index name must be provided
• Failed to delete documents by filter
• Index not found
• Unsupported search type:

AI-assisted analysis of alibaba/spring-ai-alibaba@f82da0b50f (2026-09-09). Data as JSON: /api/errors/36c982e33b27b2fb. Report an issue: GitHub.

Appendix: source

Thrown at spring-ai-alibaba-admin/spring-ai-alibaba-admin-server-core/src/main/java/org/springframework/ai/vectorstore/elasticsearch/ElasticsearchVectorStore.java:502

						.size((int) (1.5 * searchRequest.getTopK())),
					Document.class);

			return res.hits()
				.hits()
				.stream()
				.map(x -> toDocument(x, SearchType.FULL_TEXT))
				.collect(Collectors.toList());
		}
		catch (IOException e) {
			throw new BizException(ErrorCode.DOCUMENT_RETRIEVAL_ERROR.toError(), e);
		}
	}

	protected List<Document> searchByHybrid(SearchRequest searchRequest) {
		List<CompletableFuture<List<Document>>> futureList = new ArrayList<>();

		if (searchRequest.getHybridWeight() < 0 || searchRequest.getHybridWeight() > 1) {
			throw new IllegalArgumentException("hybrid alpha should be between 0 ~ 1.");
		}

		try {
			CompletableFuture<List<Document>> textFuture = CompletableFuture.supplyAsync(() -> {
				int textTopK = Math.round(searchRequest.getTopK() * (1 - searchRequest.getHybridWeight()));
				return searchByFullText(SearchRequest.builder()
					.query(searchRequest.getQuery())
					.similarityThreshold(searchRequest.getSimilarityThreshold())
					.topK(textTopK)
					.filterExpression(searchRequest.getFilterExpression())
					.build());
			}, DEFAULT_TASK_EXECUTOR);
			futureList.add(textFuture);

			// 基于向量检索召回内容
			CompletableFuture<List<Document>> vectorFuture = CompletableFuture.supplyAsync(() -> {
				int textTopK = Math.round(searchRequest.getTopK() * searchRequest.getHybridWeight());
				return searchBySemantic(SearchRequest.builder()

View on GitHub (pinned to f82da0b50f)