spring-projects/spring-ai · error · RuntimeException

Got an unexpected HTTP error: %s

Error message

Got an unexpected HTTP error: %s

What it means

GemFireVectorStore's handleHttpClientException converts REST client exceptions into RuntimeExceptions. When the HTTP status is neither NOT_FOUND nor BAD_REQUEST (e.g. 500, 503, 401), it throws this generic 'Got an unexpected HTTP error' wrapping the original exception. It signals that GemFire's REST management endpoint rejected the request in a way the store does not specifically classify.

Source

Thrown at vector-stores/spring-ai-gemfire-store/src/main/java/org/springframework/ai/vectorstore/gemfire/GemFireVectorStore.java:347

	/**
	 * Handles exceptions that occur during HTTP client operations and maps them to
	 * appropriate runtime exceptions.
	 * @param ex the exception that occurred during HTTP client operation
	 * @return a mapped runtime exception corresponding to the HTTP client exception
	 */
	private Throwable handleHttpClientException(Throwable ex) {
		if (!(ex instanceof WebClientResponseException clientException)) {
			throw new RuntimeException(String.format("Got an unexpected error: %s", ex));
		}

		if (clientException.getStatusCode().equals(org.springframework.http.HttpStatus.NOT_FOUND)) {
			throw new RuntimeException(String.format("Index %s not found: %s", this.indexName, ex));
		}
		else if (clientException.getStatusCode().equals(org.springframework.http.HttpStatus.BAD_REQUEST)) {
			throw new RuntimeException(String.format("Bad Request: %s", ex));
		}
		else {
			throw new RuntimeException(String.format("Got an unexpected HTTP error: %s", ex));
		}
	}

	@Override
	public VectorStoreObservationContext.Builder createObservationContextBuilder(String operationName) {
		return VectorStoreObservationContext.builder(VectorStoreProvider.GEMFIRE.value(), operationName)
			.collectionName(this.indexName)
			.dimensions(this.embeddingModel.dimensions())
			.fieldName(EMBEDDINGS);
	}

	public static class CreateRequest {

		@JsonProperty("name")
		private final String indexName;

		@JsonProperty("beam-width")
		private final int beamWidth;

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Inspect the wrapped exception 'ex' message in the stack trace to find the real HTTP status and server response body.
2. Verify gemfire.host/port and management endpoint configuration point to a running GemFire cluster.
3. Check GemFire server logs for the corresponding 5xx error and fix the server-side cause.
4. If auth-related, supply correct credentials for the GemFire REST API.
5. Retry the operation if the failure was transient (503/overload).

Example fix

// before
vectorStore.similaritySearch(query); // opaque RuntimeException
// after
try {
    vectorStore.similaritySearch(query);
} catch (RuntimeException e) {
    logger.error("GemFire HTTP call failed: {}", e.getCause(), e);
    // inspect cause for HTTP status, then retry or reconfigure
}

// Optionally pre-check GemFire REST endpoint health before store ops:
// curl -f http://${host}:${port}/gemfire/v1 && echo ok
boolean gemfireReachable(String host, int port) {
    try (var s = new java.net.Socket(host, port)) { return true; }
    catch (java.io.IOException e) { return false; }
}

try {
    vectorStore.similaritySearch(request);
} catch (RuntimeException e) {
    Throwable cause = e.getCause();
    // log cause (HTTP status + body), decide retry vs reconfigure
}

When it happens

Trigger: Calling GemFireVectorStore operations (e.g. afterPropertiesSet creating the index, similaritySearch, add) when the GemFire REST call returns an HTTP status other than 404 or 400 — server-side 500 errors, auth failures (401/403), gateway 502/503.

Common situations: GemFire server overloaded or crashing, wrong management endpoint URL/port, missing security credentials, GemFire version returning non-standard status codes, proxy/load balancer intercepting requests.

Understand the failure class

Background: "API error: {status}" and "HTTP 401/403/404/429/5xx" errors: non-2xx HTTP responses explained — this error's family across 27 libraries.

Related errors

• Index %s not found: %s
• Bad Request: %s
• Failed to initialize ChromaVectorStore
• Failed to delete documents by filter
• Not supported expression type: {expressionType}

AI-assisted analysis of spring-projects/spring-ai@98a7beda4f (2026-09-11). Data as JSON: /api/errors/7bd6ef03f9ef2503. Report an issue: GitHub.