Troubleshooting Common Errors in aisuite: Provider Loading and Parameter Validation

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 and 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 and aisuite/provider.py:

1. Configuration Parsing: Client.__init__ receives provider_configs and calls _initialize_providers (lines 68-74 in 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)
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)

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

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:

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:

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:

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:

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

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