# 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](https://goaisdk.com/docs/troubleshooting/common-errors.md)** - Solutions for the most frequent SDK errors
- **[Provider Errors](https://goaisdk.com/docs/troubleshooting/provider-errors.md)** - Troubleshooting provider-specific issues
- **[Rate Limits](https://goaisdk.com/docs/troubleshooting/rate-limits.md)** - Handling rate limiting and quota exhaustion
- **[Context Cancellation](https://goaisdk.com/docs/troubleshooting/context-cancellation.md)** - Debugging context timeout and cancellation issues
- **[Streaming Issues](https://goaisdk.com/docs/troubleshooting/streaming-issues.md)** - Solving problems with streaming responses
- **[Tool Calling Errors](https://goaisdk.com/docs/troubleshooting/tool-calling-errors.md)** - Debugging tool execution and schema issues
- **[Schema Validation](https://goaisdk.com/docs/troubleshooting/schema-validation.md)** - Fixing JSON schema validation errors
- **[Performance](https://goaisdk.com/docs/troubleshooting/performance.md)** - Optimizing slow operations and memory usage
- **[Debugging](https://goaisdk.com/docs/troubleshooting/debugging.md)** - Comprehensive debugging techniques

## Quick Diagnostic Guide

### Error Messages

If you see specific error messages:

- `context deadline exceeded` → See [Context Cancellation](https://goaisdk.com/docs/troubleshooting/context-cancellation.md)
- `rate limit exceeded` → See [Rate Limits](https://goaisdk.com/docs/troubleshooting/rate-limits.md)
- `invalid API key` → See [Provider Errors](https://goaisdk.com/docs/troubleshooting/provider-errors.md)
- `schema validation failed` → See [Schema Validation](https://goaisdk.com/docs/troubleshooting/schema-validation.md)
- `tool execution failed` → See [Tool Calling Errors](https://goaisdk.com/docs/troubleshooting/tool-calling-errors.md)

### Behavior Issues

If you're experiencing specific behaviors:

- Stream stops unexpectedly → See [Streaming Issues](https://goaisdk.com/docs/troubleshooting/streaming-issues.md)
- Application hangs → See [Context Cancellation](https://goaisdk.com/docs/troubleshooting/context-cancellation.md) and [Debugging](https://goaisdk.com/docs/troubleshooting/debugging.md)
- Slow responses → See [Performance](https://goaisdk.com/docs/troubleshooting/performance.md)
- Memory leaks → See [Performance](https://goaisdk.com/docs/troubleshooting/performance.md) and [Common Errors](https://goaisdk.com/docs/troubleshooting/common-errors.md)

## 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](https://goaisdk.com/docs/reference.md) 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](https://goaisdk.com/docs/troubleshooting/debugging.md#sdk-warning-logging)
for the full pattern, including wrapping the HTTP client to log raw
requests and responses.

```go
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](https://goaisdk.com/docs/troubleshooting/common-errors.md) for the most frequent issues
- Review [Debugging](https://goaisdk.com/docs/troubleshooting/debugging.md) for comprehensive debugging techniques
- Check [Error Handling](https://goaisdk.com/docs/ai-sdk-core/error-handling.md) for proper error handling patterns