Skip to content

fix(spring-ai): declare ordering for SpringAIAutoConfiguration so @ConditionalOnBean matches Spring AI model beans - #1502

Open
kongxubihai wants to merge 1 commit into
google:mainfrom
kongxubihai:fix/spring-ai-autoconfig-ordering
Open

fix(spring-ai): declare ordering for SpringAIAutoConfiguration so @ConditionalOnBean matches Spring AI model beans#1502
kongxubihai wants to merge 1 commit into
google:mainfrom
kongxubihai:fix/spring-ai-autoconfig-ordering

Conversation

@kongxubihai

Copy link
Copy Markdown

Fixes #1501

Problem

SpringAIAutoConfiguration (contrib/spring-ai) guards all four of its @Bean methods with
@ConditionalOnBean — three SpringAI variants on ChatModel/StreamingChatModel, and
springAIEmbedding on EmbeddingModel — but declares no ordering relative to the
auto-configurations that register those beans.

The result of @ConditionalOnBean depends on what has been processed so far. With no
declared ordering, evaluation order falls back to the alphabetical class-name sort, and
com.google.adk... sorts before org.springframework.ai... — so ADK's conditions are
evaluated before any Spring AI model bean definition exists. No SpringAI bean is
registered and applications fail to start:

Parameter 0 of method scienceTeacher in ...AdkJavaSpringAiDemoApplication required a bean
of type 'com.google.adk.models.springai.SpringAI' that could not be found.

springAIEmbedding is affected identically — silently: no error, just a missing bean.

Fix

Declare afterName on @AutoConfiguration, listing the Spring AI model auto-configurations
that may provide ChatModel, StreamingChatModel, or EmbeddingModel beans
(7 chat + 9 embedding entries in the commit).

Design notes:

  1. Why afterName (string) and not after (Class): this module compiles only against
    spring-ai-model; provider auto-configuration classes are not on the compile classpath.
    Names that do not exist on the classpath are ignored by the sorter, which makes string
    form the intended mechanism here — the same pattern Spring AI 1.x's own
    ChatClientAutoConfiguration used for the identical problem.
  2. How the list was derived and verified (against the published Spring AI 2.0.1 jars):
    • Read every provider module's
      META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports
      (the authoritative registration file — class-path/name-pattern guessing misses
      nested packages such as google.genai.autoconfigure.chat or vertexai.autoconfigure.embedding).
    • javap-verified the bean type of every configuration whose name alone is not
      sufficient: GoogleGenAiChatModel implements ChatModel;
      GoogleGenAiTextEmbeddingModel / VertexAiTextEmbeddingModel extend
      AbstractEmbeddingModel.
  3. Deliberately excluded (each verified, not guessed):
    • *Connection*AutoConfiguration (google-genai, vertex-ai) — register connection-details
      beans, not models;
    • VertexAiMultiModalEmbeddingAutoConfiguration — registers a DocumentEmbeddingModel,
      which does not satisfy @ConditionalOnBean(EmbeddingModel);
    • ElevenLabsAutoConfiguration — registers a text-to-speech model, not chat/embedding;
    • OllamaApiAutoConfiguration and the image/audio/moderation/OCR configurations —
      unrelated interfaces.
  4. Maintenance: new Spring AI provider modules need to be appended to this list — the
    same standing cost Spring AI 1.x accepted for this pattern. Modules introduced after
    2.0.1 are ignored harmlessly until added.

Test

New SpringAIAutoConfigurationOrderingTest places SpringAIAutoConfiguration first in
AutoConfigurations.of(...) alongside the provider configurations and
ToolCallingAutoConfiguration (the latter provides the ToolCallingManager that
OpenAiChatAutoConfiguration requires; a real application imports it automatically, the
context runner must declare it explicitly).

AutoConfigurations.of applies the same ordering rules as production auto-configuration
import (AutoConfigurationSorter#getInPriorityOrder), so:

  • Before this change the tests fail: the alphabetical order processes
    SpringAIAutoConfiguration before the provider configurations, so @ConditionalOnBean
    never matches.
  • After both tests pass, and runtime behavior flips accordingly — in a demo application,
    singleton pre-instantiation logs change from springAIEmbedding being created before
    openAiChatModel (alphabetical order, conditions evaluated too early) to OpenAI beans
    being created first followed by Auto-configuring SpringAI....

Notes

An alternative fix — dropping @ConditionalOnBean in favor of @Bean method parameter
injection, as Spring AI 2.0's own ChatClientAutoConfiguration does — would also remove
the ordering sensitivity, but changes semantics: with no model present, failure moves from
a clear startup report to a less friendly bean-creation error. The afterName declaration
is the smaller, behavior-preserving change.

Google CLA signed.

@google-cla

google-cla Bot commented Sep 11, 2026

Copy link
Copy Markdown

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

@kongxubihai
kongxubihai force-pushed the fix/spring-ai-autoconfig-ordering branch from 7d52df7 to 4c434a6 Compare September 11, 2026 05:35
@hemasekhar-p hemasekhar-p self-assigned this Sep 11, 2026
@hemasekhar-p

Copy link
Copy Markdown
Contributor

Hi @kongxubihai, thank you for your contribution. We appreciate you taking the time to submit this pull request. Currently this PR is under review by our team and we will keep you posted if any additional information is required. thank you.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

2 participants