What causes "api_base is required for hosted_vllm embeddings" in BerriAI/litellm?

Pass api_base explicitly: litellm.embedding(model='hosted_vllm/ ', input=[...], api_base='http://vllm-host:8000').

BerriAI/litellm · error · ValueError

api_base is required for hosted_vllm embeddings

Error message

api_base is required for hosted_vllm embeddings

What it means

Raised by HostedVLLM EmbeddingConfig.get_complete_url when no api_base argument was given and the HOSTED_VLLM_API_BASE environment variable is unset. Hosted vLLM is self-hosted (each deployment has its own URL), so LiteLLM has no default endpoint for embeddings and refuses to proceed with a ValueError.

Source

Thrown at litellm/llms/hosted_vllm/embedding/transformation.py:82

        # Merge with existing headers (user's headers take priority)
        return {**default_headers, **headers}

    def get_complete_url(
        self,
        api_base: str | None,
        api_key: str | None,
        model: str,
        optional_params: dict,
        litellm_params: dict,
        stream: bool | None = None,
    ) -> str:
        """
        Get the complete URL for Hosted VLLM Embedding API endpoint.
        """
        if api_base is None:
            api_base = get_secret_str("HOSTED_VLLM_API_BASE")
            if api_base is None:
                raise ValueError("api_base is required for hosted_vllm embeddings")

        # Remove trailing slashes
        api_base = api_base.rstrip("/")

        # Ensure the URL ends with /embeddings
        if not api_base.endswith("/embeddings"):
            api_base = f"{api_base}/embeddings"

        return api_base

    def transform_embedding_request(
        self,
        model: str,
        input: AllEmbeddingInputValues,
        optional_params: dict,
        headers: dict,
    ) -> dict:
        """

View on GitHub (pinned to 6c2dcb801b)

Solutions

Pass api_base explicitly: litellm.embedding(model='hosted_vllm/<model>', input=[...], api_base='http://vllm-host:8000').
Or set export HOSTED_VLLM_API_BASE=http://vllm-host:8000 (trailing slashes are stripped; /embeddings is appended if missing).
Ensure your vLLM server is actually serving /embeddings (started with --task embed or with an embedding model loaded).

Example fix

# before
litellm.embedding(model='hosted_vllm/bge-large', input=['hello'])
# raises ValueError: api_base is required for hosted_vllm embeddings

# after
litellm.embedding(
    model='hosted_vllm/bge-large',
    input=['hello'],
    api_base='http://localhost:8000',  # /embeddings appended automatically
)

Defensive patterns

Strategy: validation

Validate before calling

import os

def vllm_embed_base(api_base: str | None = None) -> str:
    base = api_base or os.environ.get("HOSTED_VLLM_API_BASE")
    if not base:
        raise ValueError("api_base or HOSTED_VLLM_API_BASE required for hosted_vllm embeddings")
    return base

Prevention

Set HOSTED_VLLM_API_BASE once per environment (it also covers chat/responses handlers).
Smoke-test embeddings after any vLLM redeploy: a 1-token embedding call catches missing base URLs and unloaded models early.

When it happens

Trigger: Calling litellm.embedding(model='hosted_vllm/<model>', input=[...]) without api_base and without HOSTED_VLLM_API_BASE in the environment. Note chat calls to hosted_vllm have a separate resolution path; the embeddings handler only checks these two sources.

Common situations: Working chat calls (env var set for the chat path or passed there) while the embedding call omits api_base; new deploy of vLLM where the embeddings endpoint env var was not added to the service; docker/k8s config missing the variable in one of several containers.

Related errors

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