spring-projects/spring-ai · error · IllegalArgumentException

Base URL must be provided for Microsoft Foundry.

Error message

Base URL must be provided for Microsoft Foundry.

What it means

OpenAiSetup.calculateBaseUrl validates that a base URL is present when the configured ModelProvider is MICROSOFT_FOUNDRY. Unlike GitHub Models or OpenAI, a Microsoft Foundry deployment has no default endpoint, so the library requires an explicit base URL (the Foundry resource endpoint). It throws IllegalArgumentException to fail fast during client setup rather than producing an unresolvable endpoint later.

Source

Thrown at models/spring-ai-openai/src/main/java/org/springframework/ai/openai/setup/OpenAiSetup.java:325

		if (modelProvider == ModelProvider.OPEN_AI) {
			if (baseUrl == null || baseUrl.isBlank()) {
				return OPENAI_URL;
			}
			return baseUrl;
		}
		else if (modelProvider == ModelProvider.GITHUB_MODELS) {
			if (baseUrl == null || baseUrl.isBlank()) {
				return GITHUB_MODELS_URL;
			}
			if (baseUrl.startsWith(GITHUB_MODELS_URL)) {
				// To support GitHub Models for specific orgs
				return baseUrl;
			}
			return GITHUB_MODELS_URL;
		}
		else if (modelProvider == ModelProvider.MICROSOFT_FOUNDRY) {
			if (baseUrl == null || baseUrl.isBlank()) {
				throw new IllegalArgumentException("Base URL must be provided for Microsoft Foundry.");
			}
			String tmpUrl = baseUrl;
			if (baseUrl.endsWith("/") || baseUrl.endsWith("?")) {
				tmpUrl = baseUrl.substring(0, baseUrl.length() - 1);
			}
			return tmpUrl;
		}
		else {
			throw new IllegalArgumentException("Unknown model provider: " + modelProvider);
		}
	}

	static Credential azureAuthentication() {
		try {
			return AzureInternalOpenAiHelper.getAzureCredential();
		}
		catch (NoClassDefFoundError e) {
			throw new IllegalArgumentException("Microsoft Foundry was detected, but no credential was provided. "

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Set the Microsoft Foundry base URL (e.g. https://<resource-name>.services.ai.azure.com) in the OpenAI chat/embedding base-url property or OpenAiApi builder.
2. If using an env var for the URL, verify it is exported and spelled correctly before starting the app.
3. If you did not intend to use Microsoft Foundry, correct the model-provider setting back to OPEN_AI or GITHUB_MODELS.

Example fix

// before
OpenAiApi.builder().modelProvider(ModelProvider.MICROSOFT_FOUNDRY).build();
// after
OpenAiApi.builder()
    .modelProvider(ModelProvider.MICROSOFT_FOUNDRY)
    .baseUrl("https://<resource-name>.services.ai.azure.com")
    .build();

if (modelProvider == ModelProvider.MICROSOFT_FOUNDRY && (baseUrl == null || baseUrl.isBlank())) {
    throw new IllegalStateException("base-url must be set when using Microsoft Foundry");
}

When it happens

Trigger: Setting spring.ai.openai... model-provider to MICROSOFT_FOUNDRY (or calling OpenAiSetup/calculatedBaseUrl with ModelProvider.MICROSOFT_FOUNDRY) while leaving the base URL property null, empty, or whitespace-only.

Common situations: Developers switch from OpenAI to Microsoft Foundry via properties but forget to set the base-url; the base-url is read from an environment variable that is unset; trailing config refactoring removed the URL; YAML/properties key typo means baseUrl resolves to null.

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

• SHA-256 not available
• Failed to read stdio connection resource
• SSE connection '<connectionName>' requires a 'url' property.
• Failed to create SSE transport for connection '<connectionNa
• The region '<region>' is not a valid region!

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