openai/openai-python · error · OpenAIError

Invalid provider. Providers must be created by an OpenAI pro

Error message

Invalid provider. Providers must be created by an OpenAI provider factory.

What it means

The provider object passed to configuration isn't a valid provider token: _get_provider_definition() only recognizes providers created by the SDK's own provider factories (stored in _provider_definitions). Unknown keys or unhashable/invalid objects raise OpenAIError with this message.

Source

Thrown at src/openai/_provider.py:65

def _create_provider(definition: _ProviderDefinition) -> _Provider:  # pyright: ignore[reportUnusedFunction]
    provider = _Provider()
    _provider_definitions[provider] = definition
    return provider


def _provider_name(provider: _Provider) -> str:  # pyright: ignore[reportUnusedFunction]
    return _get_provider_definition(provider).name


def _configure_provider(provider: _Provider) -> _ProviderRuntime:  # pyright: ignore[reportUnusedFunction]
    return _get_provider_definition(provider).configure()


def _get_provider_definition(provider: _Provider) -> _ProviderDefinition:
    try:
        return _provider_definitions[provider]
    except (KeyError, TypeError) as exc:
        raise OpenAIError("Invalid provider. Providers must be created by an OpenAI provider factory.") from exc

View on GitHub (pinned to 9917c6e28e)

Solutions

Import the provider from the SDK's provider factory (e.g. openai.providers.azure / openai(...).providers.*) instead of constructing your own
Upgrade to a matching SDK version if the provider was renamed/removed
If you need a custom base URL, use base_url configuration instead of forging a provider

Example fix

// before
client = OpenAI(provider="azure")
// after
from openai import AzureOpenAI
client = AzureOpenAI(...)

Defensive patterns

Strategy: validation

Validate before calling

from openai._provider import _provider_definitions

def provider_is_valid(p: object) -> bool:
    try:
        return p in _provider_definitions
    except TypeError:
        return False

Type guard

def is_factory_provider(p: object, client) -> bool:
    return hasattr(client, 'providers') and any(p == f() for f in client.providers.__dict__.values() if callable(f))

Try / catch

try:
    client = OpenAI(provider=provider)
except OpenAIError as e:
    if 'Invalid provider' in str(e):
        raise ValueError('use provider factories from openai.providers') from e
    raise

Prevention

Only use provider constants obtained from the SDK itself
After upgrading, re-check provider import paths

When it happens

Trigger: Passing a string, an arbitrary object, or a manually constructed/forged provider constant to a provider-related config API (e.g. with_options(provider=...) or client configuration); using a provider constant removed or renamed between SDK versions.

Common situations: Typos in provider names; copying provider constants from a different SDK version or another library; pickling/deserializing provider objects so identity is lost.

Related errors

AI-assisted analysis of openai/openai-python@9917c6e28e (2026-08-28). Data as JSON: /api/errors/d9ae1b4cef697f0c. Report an issue: GitHub.