spring-projects/spring-ai · critical · RuntimeException

java.io.IOException

Error message

java.io.IOException

What it means

createPredictionServiceClient wraps the IOException thrown by PredictionServiceClient.create() in an unchecked RuntimeException. The Google gRPC client throws IOException when it cannot construct the service (invalid settings, credential loading failure), and the library converts it so callers do not need to handle checked exceptions.

Source

Thrown at models/spring-ai-vertex-ai-embedding/src/main/java/org/springframework/ai/vertexai/embedding/text/VertexAiTextEmbeddingModel.java:242

		for (int i = 0; i < request.getInstructions().size(); i++) {

			TextInstanceBuilder instanceBuilder = TextInstanceBuilder.of(request.getInstructions().get(i))
				.taskType(taskType.name());
			if (StringUtils.hasText(finalOptions.getTitle())) {
				instanceBuilder.title(finalOptions.getTitle());
			}
			predictRequestBuilder.addInstances(VertexAiEmbeddingUtils.valueOf(instanceBuilder.build()));
		}
		return predictRequestBuilder;
	}

	// for testing
	PredictionServiceClient createPredictionServiceClient() {
		try {
			return PredictionServiceClient.create(this.connectionDetails.getPredictionServiceSettings());
		}
		catch (IOException e) {
			throw new RuntimeException(e);
		}
	}

	// for testing
	PredictResponse getPredictResponse(PredictionServiceClient client, PredictRequest.Builder predictRequestBuilder) {
		PredictResponse embeddingResponse = client.predict(predictRequestBuilder.build());
		return embeddingResponse;
	}

	private EmbeddingResponseMetadata generateResponseMetadata(String model, Integer totalTokens) {
		EmbeddingResponseMetadata metadata = new EmbeddingResponseMetadata();
		metadata.setModel(model);
		Usage usage = getDefaultUsage(totalTokens);
		metadata.setUsage(usage);
		return metadata;
	}

	private DefaultUsage getDefaultUsage(Integer totalTokens) {

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Inspect getCause() for the detailed IOException message
2. Fix the credentials path/contents referenced by the connection details
3. Verify VertexAiEmbeddingConnectionDetails settings (projectId, location, API key) are valid
4. Run `gcloud auth application-default login` for local development

Example fix

// before
var model = new VertexAiTextEmbeddingModel(factory, MyOptions.DEFAULT); // may throw RuntimeException(IOException)
// after
try {
    var model = new VertexAiTextEmbeddingModel(factory, MyOptions.DEFAULT);
} catch (RuntimeException e) {
    if (e.getCause() instanceof IOException io) {
        throw new IllegalStateException("Cannot create Vertex AI client: " + io.getMessage(), io);
    }
    throw e;
}

String credPath = System.getenv("GOOGLE_APPLICATION_CREDENTIALS"); if (credPath != null && !new File(credPath).canRead()) throw new IllegalStateException("Cannot read credentials file: " + credPath);

static boolean canCreateClient(VertexAiEmbeddingConnectionDetails d) { return d != null && StringUtils.hasText(d.getProjectId()) && StringUtils.hasText(d.getEndpoint()); }

try { PredictionServiceClient c = PredictionServiceClient.create(settings); } catch (IOException e) { throw new IllegalStateException("Vertex AI client init failed: " + e.getMessage(), e); }

When it happens

Trigger: Instantiating/calling VertexAiTextEmbeddingModel (via call -> createPredictionServiceClient) when PredictionServiceSettings cannot be created: malformed credentials file, missing scopes, bad transport, or underlying IO error reading the service account key.

Common situations: GOOGLE_APPLICATION_CREDENTIALS pointing to a missing/corrupt JSON key; wrong spring.ai.vertex.ai.* properties producing invalid settings; environment without network or quota project misconfig.

Understand the failure class

Background: "open() failed", "failed to open file", "cannot create file" — what a file open error means and how to fix it — this error's family across 42 libraries.

Related errors

• Unsupported image mime type:
• Unsupported media type:
• model cannot be null or empty
• Title is only valid with task_type=RETRIEVAL_DOCUMENT
• java.io.IOException

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