BerriAI/litellm · error · ValueError

AzureOpenAI client is not an instance of AsyncAzureOpenAI. M

Error message

AzureOpenAI client is not an instance of AsyncAzureOpenAI. Make sure you passed an AsyncAzureOpenAI client.

What it means

litellm's Azure file-management wrapper dispatches on the _is_async flag: when True it requires the resolved client to be an AsyncAzureOpenAI (or AsyncOpenAI) instance. This ValueError means the async branch was taken but the client resolved from get_azure_openai_client() is a synchronous AzureOpenAI/OpenAI object. It is a programming/config error raised before any network call is made.

Source

Thrown at litellm/llms/azure/files/handler.py:80

        client: AzureOpenAI | AsyncAzureOpenAI | OpenAI | AsyncOpenAI | None = None,
        litellm_params: dict | None = None,
    ) -> OpenAIFileObject | Coroutine[Any, Any, OpenAIFileObject]:
        openai_client: AzureOpenAI | AsyncAzureOpenAI | OpenAI | AsyncOpenAI | None = self.get_azure_openai_client(
            litellm_params=litellm_params or {},
            api_key=api_key,
            api_base=api_base,
            api_version=api_version,
            client=client,
            _is_async=_is_async,
        )
        if openai_client is None:
            raise ValueError(
                "AzureOpenAI client is not initialized. Make sure api_key is passed or OPENAI_API_KEY is set in the environment."
            )

        if _is_async is True:
            if not isinstance(openai_client, (AsyncAzureOpenAI, AsyncOpenAI)):
                raise ValueError(
                    "AzureOpenAI client is not an instance of AsyncAzureOpenAI. Make sure you passed an AsyncAzureOpenAI client."
                )
            return self.acreate_file(create_file_data=create_file_data, openai_client=openai_client)
        response: Final = cast(AzureOpenAI | OpenAI, openai_client).files.create(
            **self._prepare_create_file_data(create_file_data)
        )
        return OpenAIFileObject(**response.model_dump())

    async def afile_content(
        self,
        file_content_request: FileContentRequest,
        openai_client: AsyncAzureOpenAI | AsyncOpenAI,
    ) -> HttpxBinaryResponseContent:
        response: Final = await openai_client.files.content(**file_content_request)
        return HttpxBinaryResponseContent(response=response.response)

    def file_content(
        self,

View on GitHub (pinned to 6c2dcb801b)

Solutions

Pass an AsyncAzureOpenAI instance: AsyncAzureOpenAI(api_key=..., azure_endpoint=..., api_version=...) in the client= argument.
If you intended a synchronous call, call the sync entrypoint (do not set _is_async=True) so the sync files.create path is used.
Do not reuse a module-level sync client in async code; construct the async client once per event loop instead.

Example fix

# before
from openai import AzureOpenAI
client = AzureOpenAI(api_key=key, azure_endpoint=base, api_version=ver)
await litellm.azure_files.create_file(create_file_data, client=client, _is_async=True)  # raises

# after
from openai import AsyncAzureOpenAI
client = AsyncAzureOpenAI(api_key=key, azure_endpoint=base, api_version=ver)
await litellm.azure_files.create_file(create_file_data, client=client, _is_async=True)

Defensive patterns

Strategy: type-guard

Validate before calling

from openai import AsyncAzureOpenAI, AsyncOpenAI

def assert_async_client(client: object) -> None:
    if not isinstance(client, (AsyncAzureOpenAI, AsyncOpenAI)):
        raise TypeError(f'expected an async client, got {type(client).__name__}')

Type guard

from openai import AsyncAzureOpenAI, AsyncOpenAI

def is_async_client(client: object) -> bool:
    return isinstance(client, (AsyncAzureOpenAI, AsyncOpenAI))

Try / catch

try:
    await handler.create_file(data, client=client, _is_async=True)
except ValueError as e:
    if 'AsyncAzureOpenAI' in str(e):
        raise TypeError('sync client passed to async files API') from e
    raise

Prevention

Build the client in the same layer that decides sync vs async so the type always matches the call path.
Name variables async_client / sync_client explicitly instead of a shared 'client'.
In tests, parametrize fixtures over both client kinds and assert dispatch works for each.

When it happens

Trigger: Calling azure_files_instance.create_file(..., _is_async=True) while supplying a sync AzureOpenAI client via the client= argument; or a context where get_azure_openai_client returns the cached sync client (e.g. a client previously constructed without async semantics) and _is_async=True is forced by an async caller path.

Common situations: Porting sync litellm file scripts to asyncio and reusing the old sync client object; mixed async frameworks (FastAPI handlers) where a module-level sync AzureOpenAI client is shared; passing a client built as AzureOpenAI(...) instead of AsyncAzureOpenAI(...).

Related errors

AI-assisted analysis of BerriAI/litellm@6c2dcb801b (2026-08-15). Data as JSON: /api/errors/9b5ed79805c4ec88. Report an issue: GitHub.