spring-projects/spring-ai · error · RuntimeException

java.io.IOException

Error message

java.io.IOException

What it means

VertexAiEmbeddingConnectionDetails.Builder.build() constructs PredictionServiceSettings with the configured endpoint; this performs validation/IO that can throw IOException (bad endpoint format, failed credential/settings resolution). The builder wraps it in a RuntimeException, aborting construction of the connection details.

Source

Thrown at models/spring-ai-vertex-ai-embedding/src/main/java/org/springframework/ai/vertexai/embedding/VertexAiEmbeddingConnectionDetails.java:179

					this.location = DEFAULT_LOCATION;
				}
				else {
					this.endpoint = this.location + DEFAULT_ENDPOINT_SUFFIX;
				}
			}

			if (!StringUtils.hasText(this.publisher)) {
				this.publisher = DEFAULT_PUBLISHER;
			}

			if (this.predictionServiceSettings == null) {
				try {
					this.predictionServiceSettings = PredictionServiceSettings.newBuilder()
						.setEndpoint(this.endpoint)
						.build();
				}
				catch (IOException e) {
					throw new RuntimeException(e);
				}
			}

			Assert.state(this.location != null, "location must not be null");
			return new VertexAiEmbeddingConnectionDetails(this.projectId, this.location, this.publisher,
					this.predictionServiceSettings);
		}

	}

}

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Set the endpoint to the canonical Vertex AI format, e.g. "us-central1-aiplatform.googleapis.com:443" (no scheme).
2. Check that the wrapped IOException cause details the actual settings resolution problem and fix accordingly.
3. Verify Google Cloud credentials (GOOGLE_APPLICATION_CREDENTIALS / ADC) are valid before building.
4. Ensure outbound network access to googleapis.com from the runtime.

Example fix

// before
VertexAiEmbeddingConnectionDetails.newBuilder()
    .withEndpoint("https://us-central1-aiplatform.googleapis.com")
    .build();
// after
VertexAiEmbeddingConnectionDetails.newBuilder()
    .withEndpoint("us-central1-aiplatform.googleapis.com:443")
    .build();

String endpoint = "us-central1-aiplatform.googleapis.com:443";
if (!endpoint.matches("[a-z0-9-]+-aiplatform\\.googleapis\\.com:443")) {
    throw new IllegalArgumentException("Vertex AI endpoint must be <region>-aiplatform.googleapis.com:443");
}

try {
    details = VertexAiEmbeddingConnectionDetails.newBuilder()
        .withProjectId(projectId).withLocation(location).withEndpoint(endpoint).build();
} catch (RuntimeException e) {
    if (e.getCause() instanceof IOException io) {
        throw new IllegalStateException("Vertex settings build failed: " + io.getMessage(), io);
    }
    throw e;
}

When it happens

Trigger: Calling VertexAiEmbeddingConnectionDetails.newBuilder()...build() where PredictionServiceSettings.newBuilder().setEndpoint(endpoint).build() throws IOException — typically an invalid or unreachable endpoint value or problems resolving default settings/credentials.

Common situations: Typo in the endpoint (must be in the form <region>-aiplatform.googleapis.com:443); endpoint set to a full https:// URL when the client expects host:port; credential scoping failing while building default settings; network restrictions during settings initialization.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Vertex AI mode requires both 'project-id' and 'location' to
• Vertex AI mode requires both 'project-id' and 'location' to
• SHA-256 not available
• Failed to read stdio connection resource
• SSE connection '<connectionName>' requires a 'url' property.

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