Troubleshooting

This page collates common errors from across the TramAI guides into a single reference.

Model Not Found

Symptom: ModelNotFoundException: Model 'xxx' is not mapped to any provider.

Cause: An operation references a model name that has not been mapped to a provider in your TramAI engine configuration.

Solution: Ensure every model is explicitly mapped:

val tramai = Tramai {
    provider(OpenAiProvider(...), name = "openai")
    model("gpt-4o", "openai") // required mapping
}

Structured Output Parsing Fails

Symptom: StructuredOutputException: Failed to parse AI response into type 'YourType'. Logs show invalid JSON or wrong schema.

Cause: The model failed to follow the requested output format. Common with smaller models.

Solutions:

1. Use a more capable model (gpt-4o, claude-sonnet-4-20250514)
2. Add explicit format instructions in your @Operation(prompt = "...")
3. Check that retries are enabled — TramAI feeds validation errors back to the model on retry
4. Default retries: 2. Configurable via @Operation(maxRetries = N)

Provider Authentication Failures

Symptom: ProviderException: Unauthorized (401), AuthenticationException, or similar auth error.

Causes: Missing, invalid, expired, or rotated API key. Environment variable not picked up.

Solutions:

• Verify the environment variable: echo $OPENAI_API_KEY
• In Spring Boot, check application.yaml:

  tramai:
    providers:
      openai:
        api-key: ${OPENAI_API_KEY}
  

• Use SecretValueResolver for secure credential management
• Check that the API key has not been rotated or revoked at the provider console
• For Azure OpenAI, verify the endpoint URL and API version are correct

Provider Timeout Errors

Symptom: ProviderException: Request timed out, java.net.SocketTimeoutException, or Read timed out.

Causes: Network latency, provider overload, or tight client timeouts.

Solutions:

• Increase the HTTP client timeout in your provider configuration
• Check network connectivity between your application and the provider endpoint
• Verify proxy/firewall settings if using a corporate network
• For Ollama, ensure the service is running and accessible: curl http://localhost:11434/api/tags
• Consider circuit breaker and retry configuration to handle transient timeouts

Provider Rate Limit Errors

Symptom: ProviderException: 429 Too Many Requests, RateLimitError, or Retry-After headers in logs.

Causes: Exceeding the provider's API rate limit or token-per-minute quota.

Solutions:

• Enable TramAI retry policy with exponential backoff (built into the engine):

  retryPolicy(
      RetryPolicySettings(
          maxRetryAfterMillis = 20_000,
          jitterRatio = 0.1,
      ),
  )
  

• Reduce concurrent operation throughput
• Increase your provider plan tier if rate limits are consistently hit
• Implement a token-bucket rate limiter on your side for predictable usage

Spring Bean Injection Fails

Symptom: NoSuchBeanDefinitionException: No qualifying bean of type 'YourAiService' available.

Causes and solutions:

1. Ensure @AiService is on the interface, not an implementation class
2. Check that the interface is in a package scanned by Spring (under @SpringBootApplication or explicit @ComponentScan)
3. Verify the tramai-spring dependency is present on the classpath
4. If using @EnableTramai, verify it is present on a configuration class

ClassNotFound / NoClassDefFoundError

Symptom: java.lang.NoClassDefFoundError: dev/tramai/core/... at runtime.

Cause: Missing optional module dependency.

Solution: Ensure all required modules are in your build file:

implementation("dev.tramai:tramai-standalone:0.3.1")
implementation("dev.tramai:tramai-openai:0.3.1")

TramAI modules are opt-in. You need:

• tramai-standalone or tramai-spring as the runtime entry point
• at least one provider module (tramai-openai, tramai-anthropic, tramai-ollama)
• tramai-structured is pulled transitively by standalone/spring
• optional modules: tramai-observability, tramai-orchestration, tramai-scheduler, tramai-server, tramai-mcp, tramai-platform

Native Image Build Fails

Symptom: com.oracle.svm.core.jdk.proxy.DynamicProxyProxyCreationError or missing proxy at runtime.

Cause: @AiService interface not registered in GraalVM proxy-config.json.

Solution: Generate and include proxy metadata:

NativeImageProxyConfig.write(
    outputPath = Path.of("src/main/resources/META-INF/native-image/.../proxy-config.json"),
    InvoiceAnalyzer::class,
)

See Native Image for the full workflow.

Native Image: Reflection Errors

Symptom: java.lang.ClassNotFoundException or reflective access errors in native image.

Cause: TramAI or provider libraries need reflection hints not included in the image.

Common fixes:

• Add --enable-url-protocols=https if using HTTPS providers
• Add Jackson reflection hints for your data classes
• Add -H:ReflectionConfigurationFiles=... for provider-specific reflection
• Test with -H:+ReportUnsupportedElementsAtRuntime for diagnostics

Spring Boot Configuration Issues

Symptom: TramAI beans are not configured as expected, or auto-configuration fails silently.

Common causes:

Provider-Specific Errors

Builder Configuration Mistakes

Common mistakes when using the Tramai { ... } builder DSL.

Orchestration Errors

Symptom: ExperimentalTramAIOrchestration opt-in required.

Cause: The orchestration module is marked experimental in code.

Fix: Add the opt-in annotation:

@OptIn(ExperimentalTramAIOrchestration::class)
fun buildWorkflow() {
    // workflow code here
}

Scheduler Errors

Server Errors

Platform Errors

Logging Diagnostics

Enable DEBUG logging for TramAI internals to trace execution:

logging:
  level:
    dev.tramai: DEBUG

This reveals:

• provider resolution decisions
• retry attempt pacing
• structured output parsing details
• circuit breaker state transitions
• interceptor execution order

Still Having Trouble?

• Enable DEBUG logging for dev.tramai to see detailed execution traces
• Check the GitHub Issues for known problems
• Review the relevant guide page for your use case:
  • Production Hardening
  • Native Image
  • Scheduling
  • Server
  • Platform Operations