spring-projects/spring-ai · error · IllegalStateException

Vertex AI mode requires both 'project-id' and 'location' to

Error message

Vertex AI mode requires both 'project-id' and 'location' to be configured.

What it means

The Google GenAI image connection auto-configuration applies the same fail-fast mode validation as the chat one: if vertex-ai mode is enabled for the image connection but either project-id or location is missing, googleGenAiImageConnectionDetails throws this IllegalStateException because a Vertex AI client cannot be constructed.

Source

Thrown at auto-configurations/models/spring-ai-autoconfigure-model-google-genai/src/main/java/org/springframework/ai/model/google/genai/autoconfigure/image/GoogleGenAiImageConnectionAutoConfiguration.java:75

		boolean hasLocation = StringUtils.hasText(connectionProperties.getLocation());
		boolean hasVertexConfig = hasProject && hasLocation;

		// Ambiguity Guard: Professional logging
		if (hasApiKey && hasVertexConfig) {
			if (connectionProperties.isVertexAi()) {
				logger.info(
						"Both API Key and Vertex AI config detected. Vertex AI mode is explicitly enabled; the API key will be ignored.");
			}
			else {
				logger.warn("Both API Key and Vertex AI config detected. Defaulting to Gemini Developer API (API Key). "
						+ "To use Vertex AI instead, set 'spring.ai.google.genai.vertex-ai=true'.");
			}
		}

		// Mode Selection with Fail-Fast Validation
		if (connectionProperties.isVertexAi()) {
			if (!hasVertexConfig) {
				throw new IllegalStateException(
						"Vertex AI mode requires both 'project-id' and 'location' to be configured.");
			}
			configureVertexAi(connectionBuilder, connectionProperties);
		}
		else if (hasApiKey) {
			connectionBuilder.apiKey(connectionProperties.getApiKey());
		}
		else if (hasVertexConfig) {
			logger.debug("Project ID and Location detected. Defaulting to Vertex AI mode.");
			configureVertexAi(connectionBuilder, connectionProperties);
		}
		else {
			throw new IllegalStateException("Incomplete Google GenAI configuration: Provide 'api-key' for Gemini API "
					+ "or 'project-id' and 'location' for Vertex AI.");
		}

		return connectionBuilder.build();
	}

View on GitHub (pinned to 98a7beda4f)

Solutions

Set both project-id and location in the image connection properties (spring.ai.google.genai.image.project-id / .location).
If Vertex AI was not intended, disable vertex-ai and supply spring.ai.google.genai.image.api-key instead.
Confirm the active Spring profile / environment actually carries the Vertex properties at deploy time.

Example fix

// before
spring.ai.google.genai.image.vertex-ai=true
# location missing
// after
spring.ai.google.genai.image.vertex-ai=true
spring.ai.google.genai.image.project-id=my-gcp-project
spring.ai.google.genai.image.location=us-central1

Defensive patterns

Strategy: validation

Validate before calling

if (imageProps.isVertexAi() && (imageProps.getProjectId() == null || imageProps.getLocation() == null))
    throw new IllegalStateException("image vertex-ai=true requires project-id and location");

Prevention

Mirror chat Vertex settings (project-id, location) in the image properties when enabling vertex-ai there.
Verify per-feature property overrides in profiles don't drop required Vertex keys.
Document required GCP properties for each GenAI module in your team runbook.

When it happens

Trigger: googleGenAiImageConnectionDetails bean method runs with connectionProperties.isVertexAi() true while spring.ai.google.genai.image (or its connection properties) lacks a non-null project-id or location, so hasVertexConfig is false.

Common situations: Enabling vertex-ai on the image properties after previously using api-key, without adding project-id/location; image-specific properties being overridden by a profile that drops the Vertex settings; Kubernetes config missing the GCP project/location env values.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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