How to Troubleshoot Provider-Specific Errors in AISuite

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). 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:

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) 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, line 153
"Google Speech-to-Text error: …"	Missing GOOGLE_API_KEY or malformed request payload	google_provider.py, line 381
"Deepgram streaming error: …"	Incorrect endpoint or revoked streaming token	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:

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

Debug logs appear throughout the codebase—for example, in 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) line 21 for the api_key handling pattern. The repository's .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__:

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/ directory contains detailed setup instructions for each service:

• guides/openai.md – authentication and rate limits
• guides/google.md – Google Cloud credentials and project setup

5. Run Provider Unit Tests Locally

The test suite in tests/providers/ includes sanity checks that deliberately trigger error paths. Run provider-specific tests to verify your credentials:

pytest -k openai_provider tests/providers/test_openai_provider.py

Lines 156–158 of tests/providers/test_openai_provider.py demonstrate how the test suite exercises error conditions.

Complete Error Handling Examples

Basic Transcription with Error Recovery

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

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

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	Abstract Provider class, LLMError, ASRError, ProviderFactory
aisuite/client.py	High-level client with lazy provider loading
aisuite/providers/openai_provider.py	OpenAI implementation; ASRError wrapping at line 153
aisuite/providers/google_provider.py	Google Speech-to-Text; error handling at line 381
aisuite/providers/deepgram_provider.py	Deepgram streaming; errors at line 242
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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}