tessl/maven-org-springframework-ai--spring-ai-spring-boot-autoconfigure
Spring AI Spring Boot Auto Configuration modules providing automatic setup for AI models, vector stores, MCP, and retry capabilities
troubleshooting.mddocs/reference/
Troubleshooting Guide
Common issues and solutions for Spring AI Spring Boot Auto Configuration.
Autoconfiguration Issues
Issue: Beans Not Created
Problem: Expected autoconfiguration beans are not available.
Diagnosis:
# Enable autoconfiguration debug logging
logging.level.org.springframework.boot.autoconfigure=DEBUGCommon Causes:
- Required classes not on classpath
- Property disabled autoconfiguration
- Conditional requirements not met
- Conflicting bean definitions
Solutions:
# Check autoconfiguration report
./mvnw spring-boot:run --debug
# Verify dependencies
./mvnw dependency:tree
# Check conditional evaluation
# Look for "did not match" in logsAuthentication Issues
Issue: API Key Errors
Problem: 401 Unauthorized or 403 Forbidden errors.
Solutions:
# Use environment variables
spring.ai.openai.api-key=${OPENAI_API_KEY}
# Verify no whitespace
# spring.ai.openai.api-key=sk-... (no spaces)
# Check API key validity
# Test with curl or provider's playgroundIssue: Azure OpenAI Authentication
Problem: Azure authentication failures.
Solutions:
# Verify endpoint format
spring.ai.azure.openai.endpoint=https://RESOURCE.openai.azure.com
# Use correct API key (not OpenAI key)
spring.ai.azure.openai.api-key=AZURE_KEY
# Or use Azure AD
# Configure via AzureOpenAIClientBuilderCustomizerRate Limiting
Issue: Frequent 429 Errors
Problem: Hitting rate limits frequently.
Solutions:
# Configure aggressive retry
spring.ai.retry.on-http-codes=429
spring.ai.retry.max-attempts=10
spring.ai.retry.backoff.initial-interval=5s
spring.ai.retry.backoff.multiplier=3
# Implement request queuing (see edge-cases.md)Vector Store Issues
Issue: Schema Initialization Fails
Problem: Schema creation errors on startup.
Solutions:
# Check database permissions
# Ensure user has CREATE TABLE rights
# For existing tables
spring.ai.vectorstore.pgvector.initialize-schema=never
# For development
spring.ai.vectorstore.pgvector.initialize-schema=always
# Remove existing table first
spring.ai.vectorstore.pgvector.remove-existing-vector-store-table=trueIssue: Dimension Mismatch
Problem: Vector dimension mismatch errors.
Solutions:
# Ensure dimensions match embedding model
# OpenAI ada-002: 1536
spring.ai.vectorstore.pgvector.dimensions=1536
# Sentence transformers: 768
spring.ai.vectorstore.milvus.embedding-dimension=768
# Check embedding model documentationMCP Issues
Issue: MCP Client Not Connecting
Problem: Cannot connect to MCP server.
Diagnosis:
# Enable debug logging
logging.level.org.springframework.ai.mcp=DEBUG
logging.level.io.modelcontextprotocol=DEBUGSolutions:
# Verify command and args for stdio
spring.ai.mcp.client.stdio.connections.server.command=/usr/bin/node
spring.ai.mcp.client.stdio.connections.server.args[0]=/full/path/to/server.js
# Increase timeout
spring.ai.mcp.client.request-timeout=60s
# Check server is running (for SSE/HTTP)
# curl http://localhost:8080/ssePerformance Issues
Issue: Slow Response Times
Solutions:
# Use faster models
spring.ai.openai.chat.options.model=gpt-3.5-turbo
# Reduce max tokens
spring.ai.openai.chat.options.max-tokens=500
# Use streaming
# Implement: chatModel.stream(prompt)
# Enable connection pooling
spring.datasource.hikari.maximum-pool-size=20Issue: High Memory Usage
Solutions:
- Limit conversation history length
- Enable TTL for chat memory
- Use batch operations efficiently
- Monitor heap usage
Native Image Issues
Issue: Build Failures
Solutions:
# Collect runtime hints
java -agentlib:native-image-agent=config-output-dir=src/main/resources/META-INF/native-image \
-jar target/my-app.jar
# Add reflection configuration
# Create reflect-config.json
# Enable verbose build
./mvnw -Pnative native:compile -DverboseSee Native Image Documentation →
See Edge Cases →
Getting Help
- Check Logs: Enable DEBUG logging for Spring AI packages
- Verify Configuration: Use
--debugflag to see autoconfiguration report - Test Dependencies: Verify all required classes on classpath
- Review Documentation: Check provider-specific documentation
- Check GitHub Issues: Spring AI project issues