# Troubleshooting Common Errors in aisuite: Provider Loading and Parameter Validation

> Troubleshoot common aisuite errors like provider loading failures and parameter validation issues. Learn to fix invalid keys, import problems, and configuration gaps for seamless AI integration.

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

---

**aisuite dynamically loads AI providers via `ProviderFactory` and validates parameters through `ParamValidator`, with most errors arising from invalid provider keys, import failures, missing configuration fields, or strict validation modes that reject unrecognized parameters.**

aisuite abstracts interactions with LLM and ASR services behind a unified **Provider** interface. When you request a model using the `provider:model` syntax (e.g., `openai:gpt-4o`), the framework parses the provider key, dynamically imports the corresponding module from `aisuite/providers/`, and validates all parameters against provider-specific schemas. Understanding the exact flow through [`aisuite/provider.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/provider.py) and [`aisuite/framework/asr_params.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/framework/asr_params.py) enables rapid diagnosis of configuration failures and runtime errors.

## Understanding the Provider Loading Architecture

### The Initialization Pipeline

Provider loading follows a strict sequence defined in [`aisuite/client.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/client.py) and [`aisuite/provider.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/provider.py):

1. **Configuration Parsing**: `Client.__init__` receives `provider_configs` and calls `_initialize_providers` (lines 68-74 in [`aisuite/client.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/client.py))
2. **Key Validation**: `ProviderFactory._validate_provider_key` checks if the key matches a file `<key>_provider.py` in the providers directory (lines 21-25 in [`aisuite/provider.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/provider.py))
3. **Dynamic Instantiation**: `ProviderFactory.create_provider` constructs the class name `{Key}Provider`, imports the module, and instantiates it with the provided config (lines 95-110 in [`aisuite/provider.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/provider.py))

The framework stores successful instantiations in `client.providers` and routes all subsequent API calls through these cached instances.

### Common Provider Loading Errors

**Invalid provider key** errors occur when the key does not correspond to a provider file. The factory raises `ValueError: Invalid provider key 'foo'` because it cannot locate [`aisuite/providers/foo_provider.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/providers/foo_provider.py). Verify spelling and ensure you use the correct `provider:model` syntax.

**Import errors** happen when the module exists but raises exceptions during import, typically from missing dependencies or syntax errors. The error manifests as `ImportError: Could not import module aisuite.providers.foo_provider`. Test imports manually with `python -c "import aisuite.providers.foo_provider"` and install required extras (e.g., `pip install aisuite[mcp]`).

**Missing required configuration** triggers `KeyError` or custom validation messages from the provider's `__init__` method. Most providers require an `api_key` field in the configuration dictionary passed to `Client`.

**Streaming unsupported** errors appear as `LLMError: OpenaiProvider does not support streaming chat completions` when calling streaming methods on providers that haven't overridden `chat_completions_create_stream`. Use the synchronous `chat_completions_create` method instead.

## Parameter Validation and ASR Configuration Errors

### The Parameter Validation Pipeline

For audio transcription requests, aisuite validates parameters through `ParamValidator.validate_and_map` in [`aisuite/framework/asr_params.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/framework/asr_params.py) (lines 80-98). The validator performs three operations:

- **Common parameter mapping**: Translates unified options like `language` or `temperature` to provider-specific names using the `COMMON_PARAMS` dictionary
- **Provider-specific whitelist checking**: Validates remaining keys against `PROVIDER_PARAMS` for the specific provider
- **Mode-based enforcement**: Applies `extra_param_mode` behavior (`strict`, `warn`, or `permissive`) to unknown parameters

### Resolving Unknown Parameter Errors

Under `extra_param_mode="strict"` (the most restrictive setting), any parameter not found in `COMMON_PARAMS` or `PROVIDER_PARAMS` triggers `ValueError: Unknown parameter(s) foo, bar for provider openai`. This occurs at line 190-205 in [`aisuite/framework/asr_params.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/framework/asr_params.py) where the validator collects unrecognized keys and raises exceptions.

To resolve these errors, remove the offending parameters from your request, or switch to `extra_param_mode="warn"` (logs warnings but proceeds) or `"permissive"` (silently ignores unknown parameters). The default mode is `"warn"`.

## Debugging Provider Issues

### Enable Debug Logging

Set Python's logging level to `DEBUG` before client instantiation to trace provider initialization:

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

from aisuite import Client
client = Client(provider_configs={"openai": {"api_key": "sk-..."}})

```

This output reveals which provider keys are being processed and where the loading sequence fails.

### Manual Parameter Validation

Test parameter mappings without making API calls by invoking the validator directly:

```python
from aisuite.framework.asr_params import ParamValidator

validator = ParamValidator()
mapped = validator.validate_and_map("openai", {
    "model": "whisper-1",
    "language": "en",
    "temperature": 0.5
})
print(mapped)

```

## Code Examples for Error Handling

### Safely Loading Providers with Error Handling

Wrap client initialization to catch configuration errors before they crash your application:

```python
from aisuite import Client

def create_client_safe(configs, mode="warn"):
    try:
        client = Client(
            provider_configs=configs,
            extra_param_mode=mode
        )
        # Force immediate provider initialization

        client._initialize_providers()
        return client
    except ValueError as exc:
        print(f"Configuration error: {exc}")
        return None
    except ImportError as exc:
        print(f"Missing dependency: {exc}")
        return None

# Usage

client = create_client_safe({"openai": {"api_key": "sk-..."}})

```

### Using Permissive Mode for Rapid Prototyping

When experimenting with new provider features not yet in the common parameter set:

```python
client = Client(
    provider_configs={"deepgram": {"api_key": "dg-..."}},
    extra_param_mode="permissive",
)

response = client.audio.transcriptions.create(
    model="general",
    file="speech.wav",
    experimental_feature="enabled",  # Ignored rather than rejected

)

```

### Handling Unknown Provider Keys Gracefully

Validate provider keys before client construction using the factory method:

```python
from aisuite.provider import ProviderFactory

def validate_provider_key(key):
    supported = ProviderFactory.get_supported_providers()
    if key not in supported:
        print(f"Error: '{key}' not in supported providers: {supported}")
        return False
    return True

# Check before instantiation

if validate_provider_key("openai"):
    client = Client(provider_configs={"openai": {"api_key": "..."}})

```

## Summary

- **Provider loading** relies on `ProviderFactory.create_provider` in [`aisuite/provider.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/provider.py) to dynamically import `<provider>_provider.py` files and instantiate `{Provider}Provider` classes with your configuration dictionary.
- **Invalid provider keys** generate `ValueError` when the requested provider file doesn't exist in `aisuite/providers/`, while **ImportError** indicates missing dependencies or syntax errors in the provider module.
- **Parameter validation** occurs in [`aisuite/framework/asr_params.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/framework/asr_params.py) through `ParamValidator.validate_and_map`, which checks parameters against `COMMON_PARAMS` and provider-specific `PROVIDER_PARAMS` whitelists.
- **Strict validation mode** (`extra_param_mode="strict"`) rejects any unrecognized parameters, whereas `"warn"` logs warnings and `"permissive"` allows unknown parameters through to the provider.
- **Streaming support** is provider-specific; calling streaming methods on providers without `chat_completions_create_stream` implementations raises `LLMError`.

## Frequently Asked Questions

### Why do I get "Invalid provider key" even though I installed aisuite?

The error indicates that `aisuite/providers/<key>_provider.py` does not exist or isn't being detected by `ProviderFactory.get_supported_providers()`. Verify the spelling matches the filename exactly (case-sensitive) and that you're using the `provider:model` syntax. The factory scans the providers directory at runtime, so custom providers must follow the `<name>_provider.py` naming convention.

### How can I use experimental parameters that aisuite doesn't recognize?

Set `extra_param_mode="permissive"` when constructing the `Client`. This bypasses the strict whitelist validation in `ParamValidator.validate_and_map` and passes all parameters directly to the provider's API. Alternatively, use `"warn"` mode to receive warnings about unrecognized parameters while still allowing the request to proceed.

### What causes ImportError when loading a provider module?

This occurs when the provider file exists but raises an exception during import, typically from missing optional dependencies (e.g., provider-specific SDKs not installed). Run `python -c "import aisuite.providers.<provider>_provider"` to see the specific import failure. Install the required extras using pip (e.g., `pip install aisuite[openai]`) or manually install the missing package.

### Why does streaming work for some providers but raise LLMError for others?

Streaming support requires providers to implement the `chat_completions_create_stream` method. Not all providers in `aisuite/providers/` override this method—some only implement the synchronous `chat_completions_create`. Check the specific provider class in the source code to confirm streaming capability, or wrap your calls in try/except blocks to fall back to synchronous methods when streaming is unavailable.