Troubleshooting

This section provides solutions for common problems you may encounter when using the Go AI SDK. From provider errors to streaming issues, you'll find practical solutions with working code examples.

Common Issues

The most frequent issues developers face when building AI applications with Go:

• Common Errors - Solutions for the most frequent SDK errors
• Provider Errors - Troubleshooting provider-specific issues
• Rate Limits - Handling rate limiting and quota exhaustion
• Context Cancellation - Debugging context timeout and cancellation issues
• Streaming Issues - Solving problems with streaming responses
• Tool Calling Errors - Debugging tool execution and schema issues
• Schema Validation - Fixing JSON schema validation errors
• Performance - Optimizing slow operations and memory usage
• Debugging - Comprehensive debugging techniques

Quick Diagnostic Guide

Error Messages

If you see specific error messages:

• context deadline exceeded → See Context Cancellation
• rate limit exceeded → See Rate Limits
• invalid API key → See Provider Errors
• schema validation failed → See Schema Validation
• tool execution failed → See Tool Calling Errors

Behavior Issues

If you're experiencing specific behaviors:

• Stream stops unexpectedly → See Streaming Issues
• Application hangs → See Context Cancellation and Debugging
• Slow responses → See Performance
• Memory leaks → See Performance and Common Errors

Getting Help

If you can't find a solution in this troubleshooting guide:

1. Check the logs - Enable debug logging to see detailed error information
2. Review the documentation - Check the API Reference for correct usage
3. Search GitHub Issues - Your issue may already be reported or solved
4. Create a minimal reproduction - Isolate the problem in a small example
5. Report the issue - Open a GitHub issue with your reproduction case

Debug Mode

The SDK has no global log-level switch. Its built-in logging hook is the warnings logger: route provider warnings to your own logger with ai.SetLogWarnings, or see Debugging for the full pattern, including wrapping the HTTP client to log raw requests and responses.

import (
    "log"

    "github.com/digitallysavvy/go-ai/pkg/ai"
)

func main() {
    // Route SDK warnings into your own logger instead of stderr.
    ai.SetLogWarnings(func(opts ai.LogWarningsOptions) {
        for _, w := range opts.Warnings {
            log.Printf("[%s/%s] %s", opts.Provider, opts.Model, ai.FormatWarning(w, opts.Provider, opts.Model))
        }
    })

    // Your code here...
}

Next Steps

• Start with Common Errors for the most frequent issues
• Review Debugging for comprehensive debugging techniques
• Check Error Handling for proper error handling patterns