# How to Troubleshoot Provider-Specific Errors in AISuite

> Troubleshoot provider specific errors in AISuite by catching ASRError or LLMError and inspecting err.__cause__ for SDK exceptions. Resolve issues fast.

- Repository: [Andrew Ng/aisuite](https://github.com/andrewyng/aisuite)
- Tags: how-to-guide
- Published: 2026-08-03

---

**Catch `ASRError` or `LLMError` from `aisuite.provider` to handle any provider failure uniformly, then inspect `err.__cause__` to reveal the underlying SDK exception.**

AISuite unifies multiple AI services—OpenAI, Google, Deepgram, HuggingFace, and others—behind a single Python interface. However, when a provider's API key expires, a quota is exhausted, or a network request fails, you need clear strategies to diagnose and resolve the issue. This guide walks through the error architecture in `andrewyng/aisuite` and provides actionable steps to troubleshoot provider-specific errors effectively.

## Understanding AISuite's Error Architecture

### The Base Provider Class and Canonical Exceptions

At the core of AISuite's error handling is the abstract **Provider** class defined in [[`aisuite/provider.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/provider.py)](https://github.com/andrewyng/aisuite/blob/main/aisuite/provider.py). This base class establishes a consistent contract across all implementations:

- **`LLMError`** – raised for language model failures (chat completions, streaming responses)
- **`ASRError`** – raised for automatic speech recognition failures (transcriptions, streaming audio)

Every concrete provider wraps third-party SDK exceptions into these canonical types. For example, the OpenAI provider catches the native OpenAI SDK error and re-raises it as an `ASRError` with a descriptive message:

```python
raise ASRError(f"OpenAI transcription error: {e}") from e   # aisuite/providers/openai_provider.py, line 153

```

The `from e` clause preserves the original exception chain, making root-cause analysis straightforward.

### ProviderFactory and Import Errors

The **`ProviderFactory.create_provider`** method (lines 92–111 of [`aisuite/provider.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/provider.py)) handles provider instantiation. It reads configuration from environment variables or a user-supplied dict. If the requested provider cannot be imported, the factory raises a descriptive `ImportError` pointing to the missing dependency or configuration.

## Common Error Patterns and Root Causes

| Symptom | Likely Cause | Source Location |
|---------|--------------|---------------|
| "OpenAI transcription error: API Error" | Invalid/expired API key, quota exceeded, or network failure | [`openai_provider.py`](https://github.com/andrewyng/aisuite/blob/main/openai_provider.py), line 153 |
| "Google Speech-to-Text error: …" | Missing `GOOGLE_API_KEY` or malformed request payload | [`google_provider.py`](https://github.com/andrewyng/aisuite/blob/main/google_provider.py), line 381 |
| "Deepgram streaming error: …" | Incorrect endpoint or revoked streaming token | [`deepgram_provider.py`](https://github.com/andrewyng/aisuite/blob/main/deepgram_provider.py), line 242 |
| Provider cannot be created | Missing environment variable or typo in provider name | `ProviderFactory.create_provider`, lines 92–111 |

These messages originate where the provider catches native SDK exceptions and wraps them in AISuite's canonical error types.

## Step-by-Step Troubleshooting Methods

### 1. Enable Debug Logging

AISuite uses Python's standard `logging` module. Enable debug output early in your script to capture raw request payloads and exception details:

```python
import logging
logging.basicConfig(level=logging.DEBUG)

```

Debug logs appear throughout the codebase—for example, in [`aisuite/framework/asr_params.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/framework/asr_params.py)—showing exactly what parameters are sent to each provider.

### 2. Verify Configuration and Environment Variables

All providers read API credentials from either:
- A config dict passed to `AISuiteClient`
- Environment variables (fallback)

Check [[`aisuite/providers/openai_provider.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/providers/openai_provider.py)](https://github.com/andrewyng/aisuite/blob/main/aisuite/providers/openai_provider.py) line 21 for the `api_key` handling pattern. The repository's [`.env.sample`](https://github.com/andrewyng/aisuite/blob/main/.env.sample) lists required variables for every supported service.

### 3. Inspect the Wrapped Exception

Because AISuite errors use exception chaining (`from e`), you can access the original SDK exception through `err.__cause__`:

```python
from aisuite.client import AISuiteClient
from aisuite.provider import ASRError, LLMError

client = AISuiteClient()

try:
    result = client.providers["openai"].audio.transcriptions.create(
        model="whisper-1", file="speech.wav"
    )
    print("Transcription:", result.text)
except ASRError as e:
    print(f"Audio error: {e}")
    if e.__cause__:
        print(f"Original SDK error: {e.__cause__}")  # reveals OpenAI's native exception

except LLMError as e:
    print(f"LLM error: {e}")

```

### 4. Consult Provider-Specific Guides

The [`guides/`](https://github.com/andrewyng/aisuite/tree/main/guides) directory contains detailed setup instructions for each service:
- [`guides/openai.md`](https://github.com/andrewyng/aisuite/blob/main/guides/openai.md) – authentication and rate limits
- [`guides/google.md`](https://github.com/andrewyng/aisuite/blob/main/guides/google.md) – Google Cloud credentials and project setup

### 5. Run Provider Unit Tests Locally

The test suite in [`tests/providers/`](https://github.com/andrewyng/aisuite/tree/main/tests/providers) includes sanity checks that deliberately trigger error paths. Run provider-specific tests to verify your credentials:

```bash
pytest -k openai_provider tests/providers/test_openai_provider.py

```

Lines 156–158 of [`tests/providers/test_openai_provider.py`](https://github.com/andrewyng/aisuite/blob/main/tests/providers/test_openai_provider.py) demonstrate how the test suite exercises error conditions.

## Complete Error Handling Examples

### Basic Transcription with Error Recovery

```python
from aisuite.client import AISuiteClient
from aisuite.provider import ASRError, LLMError

client = AISuiteClient()

try:
    result = client.providers["openai"].audio.transcriptions.create(
        model="whisper-1", file="speech.wav"
    )
    print("Transcription:", result.text)
except ASRError as e:
    # Provider-specific failure already includes service name in message

    print(f"Audio error: {e}")
except LLMError as e:
    # Any LLM-related failure (chat completions, streaming)

    print(f"LLM error: {e}")
except Exception as e:
    # Unexpected issues outside AISuite's normalization

    print(f"Unexpected error: {e}")

```

### Debug-Enabled Chat Completion

```python
import logging
from aisuite.client import AISuiteClient
from aisuite.provider import LLMError

logging.basicConfig(level=logging.DEBUG)  # enables provider debug output

client = AISuiteClient()
provider = client.providers["groq"]

try:
    response = provider.chat_completions_create(
        model="mixtral-8x7b-32768",
        messages=[{"role": "user", "content": "Explain quantum tunnelling"}],
    )
    print(response.choices[0].message.content)
except LLMError as err:
    logging.error("Provider raised LLMError: %s", err)
    if err.__cause__:
        logging.debug("Original SDK exception: %s", err.__cause__)

```

### Inspecting Underlying SDK Exceptions

```python
except LLMError as err:
    if err.__cause__:
        print("Underlying SDK error:", err.__cause__)
    raise  # re-raise for fail-fast behavior or central error logging

```

## Key Source Files for Troubleshooting

| File | Purpose |
|------|---------|
| [`aisuite/provider.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/provider.py) | Abstract `Provider` class, `LLMError`, `ASRError`, `ProviderFactory` |
| [`aisuite/client.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/client.py) | High-level client with lazy provider loading |
| [`aisuite/providers/openai_provider.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/providers/openai_provider.py) | OpenAI implementation; `ASRError` wrapping at line 153 |
| [`aisuite/providers/google_provider.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/providers/google_provider.py) | Google Speech-to-Text; error handling at line 381 |
| [`aisuite/providers/deepgram_provider.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/providers/deepgram_provider.py) | Deepgram streaming; errors at line 242 |
| [`aisuite/providers/huggingface_provider.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/providers/huggingface_provider.py) | HuggingFace transcription and parsing errors |
| `guides/` | Provider-specific authentication and rate limit documentation |
| `.env.sample` | Required environment variables template |
| `tests/providers/` | Unit tests with deliberate error path coverage |

## Summary

- **Catch `ASRError` and `LLMError`** from `aisuite.provider` to handle any provider failure with unified exception types
- **Inspect `err.__cause__`** to access the original third-party SDK exception for deep debugging
- **Enable `logging.DEBUG`** to capture raw request payloads and provider-internal diagnostics
- **Verify environment variables** against `.env.sample` and provider-specific guides
- **Run targeted unit tests** to confirm provider instantiation with your credentials

## Frequently Asked Questions

### How do I know which exception type to catch when using AISuite?

Catch **`ASRError`** for speech-to-text operations (transcriptions, streaming audio) and **`LLMError`** for language model operations (chat completions, embeddings). Both are defined in `aisuite.provider` and imported from the top-level package. Catching these two exceptions covers all normalized provider errors in the codebase.

### Why does my error message say "OpenAI transcription error" even though I'm using a different provider?

The error message prefixes the **provider key** used during instantiation (e.g., `"openai"`, `"google"`, `"deepgram"`). Each provider wraps native SDK exceptions with a descriptive string identifying the service. This makes it immediately clear which backend service failed, even when multiple providers are configured in your application.

### How can I see the original error from the provider's SDK without the AISuite wrapper?

Access the **`__cause__` attribute** of any caught `ASRError` or `LLMError`. Because AISuite uses exception chaining (`raise ASRError(...) from e`), Python preserves the original exception in `err.__cause__`. Log or print this attribute to see the unmodified SDK error, including HTTP status codes and response bodies.

### What should I do if `AISuiteClient` raises `ImportError` when creating a provider?

This indicates the **provider class cannot be imported**, usually due to a missing optional dependency or incorrect provider key. Verify the provider name spelling in your `client.providers["provider_name"]` access. Check that you've installed the required SDK (e.g., `openai`, `google-cloud-speech`) and that all environment variables from `.env.sample` are set correctly.