spring-projects/spring-ai · error · IllegalStateException

Incomplete Google GenAI configuration: Provide 'api-key' for

Error message

Incomplete Google GenAI configuration: Provide 'api-key' for Gemini API or 'project-id' and 'location' for Vertex AI.

What it means

When neither Vertex AI credentials (project-id + location) nor a Gemini API key is configured, GoogleGenAiChatAutoConfiguration cannot build any client and throws this IllegalStateException. Unlike error 17, this fires when vertex-ai mode was not explicitly requested but no usable mode could be inferred from the configuration at all.

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:106

		}

		// 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();
	}

	private void configureVertexAi(Client.Builder builder, GoogleGenAiConnectionProperties props) throws IOException {
		Assert.hasText(props.getProjectId(), "Google GenAI project-id must be set for Vertex AI mode!");
		Assert.hasText(props.getLocation(), "Google GenAI location must be set for Vertex AI mode!");

		builder.project(props.getProjectId()).location(props.getLocation()).vertexAI(true);

		if (props.getCredentialsUri() != null) {
			try (var is = props.getCredentialsUri().getInputStream()) {
				builder.credentials(GoogleCredentials.fromStream(is));
			}
		}
	}

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Set spring.ai.google.genai.api-key for Gemini Developer API usage.
2. Or set both spring.ai.google.genai.project-id and spring.ai.google.genai.location for Vertex AI usage.
3. Verify the configuration source (application.yml, env vars, secret manager) is actually loaded at runtime — check the active profile and property prefix spelling.

Example fix

// before
# no google genai properties
// after
spring.ai.google.genai.api-key=${GEMINI_API_KEY}

if (props.getApiKey() == null && (props.getProjectId() == null || props.getLocation() == null))
    throw new IllegalStateException("Provide spring.ai.google.genai.api-key or project-id + location");

When it happens

Trigger: googleGenAiClient bean method runs where hasApiKey is false, hasVertexConfig is false, and properties.isVertexAi() is false — i.e. spring.ai.google.genai.api-key, project-id, and location are all unset, so the else branch throws.

Common situations: Deploying without injecting the API key env var/secret; properties file not loaded (wrong profile); typo in spring.ai.google.genai.* keys so nothing binds; fresh project where the chat starter was added but never configured.

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

• Required properties for TitanEmbeddingBedrockApi are missing
• InputType property for BedrockTitanEmbeddingModel is missing
• Vertex AI mode requires both 'project-id' and 'location' to
• Vertex AI mode requires both 'project-id' and 'location' to
• No embedding input is provided - instructions list is empty

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