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

GoogleGenAiChatAutoConfiguration supports two modes: Gemini Developer API (api-key) and Vertex AI (project-id + location). If properties.isVertexAi() is true but both vertex project-id and location are not present, the fail-fast validation throws this IllegalStateException because the Vertex client cannot be built.

Source

Thrown at auto-configurations/models/spring-ai-autoconfigure-model-google-genai/src/main/java/org/springframework/ai/model/google/genai/autoconfigure/chat/GoogleGenAiChatAutoConfiguration.java:93

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

		// Ambiguity Guard: Professional logging
		if (hasApiKey && hasVertexConfig) {
			if (properties.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 (properties.isVertexAi()) {
			if (!hasVertexConfig) {
				throw new IllegalStateException(
						"Vertex AI mode requires both 'project-id' and 'location' to be configured.");
			}
			configureVertexAi(builder, properties);
		}
		else if (hasApiKey) {
			builder.apiKey(properties.getApiKey());
		}
		else if (hasVertexConfig) {
			logger.debug("Project ID and Location detected. Defaulting to Vertex AI mode.");
			configureVertexAi(builder, properties);
		}
		else {
			throw new IllegalStateException("Incomplete Google GenAI configuration: Provide 'api-key' for Gemini API "
					+ "or 'project-id' and 'location' for Vertex AI.");
		}

		return builder.build();
	}

View on GitHub (pinned to 98a7beda4f)

Solutions

Set both spring.ai.google.genai.project-id and spring.ai.google.genai.location when vertex-ai=true.
If you intended the Gemini Developer API instead, remove vertex-ai=true and provide spring.ai.google.genai.api-key.
Verify the properties bind correctly (correct prefix, correct profiles, env vars present in the runtime environment).

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

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

Prevention

When toggling vertex-ai=true, add project-id and location in the same change.
Keep GCP settings in env vars and verify they exist in each deployment environment.
Add a startup health check that validates required spring.ai.google.genai properties.

When it happens

Trigger: googleGenAiClient bean method runs with spring.ai.google.genai.chat.vertex-ai=true (or equivalent) while either spring.ai.google.genai.project-id or spring.ai.google.genai.location is missing/null, so hasVertexConfig is false.

Common situations: Switching from Gemini API to Vertex AI by only flipping the vertex flag and forgetting to add project-id/location; properties defined under the wrong prefix; environment-variable based config where VERTEX_PROJECT is unset in the deployment environment.

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/114c58f9001e3f93. Report an issue: GitHub.