BerriAI/litellm · error · ValueError

Missing vertex_project - Set VERTEXAI_PROJECT environment va

Error message

Missing vertex_project - Set VERTEXAI_PROJECT environment variable or pass vertex_project parameter

What it means

ValueError raised while building the Vertex AI OCR endpoint URL: no Google Cloud project could be resolved. The handler reads vertex_project from litellm_params via VertexBase.safe_get_vertex_ai_project (which also checks VERTEXAI_PROJECT); without it the projects/{project}/locations/{location} URL cannot be built and the call aborts before any network request.

Source

Thrown at litellm/llms/vertex_ai/ocr/transformation.py:112

        https://{location}-aiplatform.googleapis.com/v1/projects/{project}/locations/{location}/publishers/mistralai/ocr

        Args:
            api_base: Vertex AI API base URL (optional)
            model: Model name (not used in URL construction)
            optional_params: Optional parameters
            litellm_params: LiteLLM parameters containing vertex_project, vertex_location

        Returns: Complete URL for Vertex AI OCR endpoint
        """
        # Extract Vertex AI parameters using safe helpers from VertexBase
        # Use safe_get_* methods that don't mutate litellm_params dict
        litellm_params = litellm_params or {}

        vertex_project: Final = VertexBase.safe_get_vertex_ai_project(litellm_params=litellm_params)
        vertex_location = VertexBase.safe_get_vertex_ai_location(litellm_params=litellm_params)

        if vertex_project is None:
            raise ValueError(
                "Missing vertex_project - Set VERTEXAI_PROJECT environment variable or pass vertex_project parameter"
            )

        if vertex_location is None:
            vertex_location = "us-central1"

        # Get API base URL
        if api_base is None:
            api_base = get_vertex_base_url(vertex_location)

        # Ensure no trailing slash
        api_base = api_base.rstrip("/")

        # Vertex AI OCR endpoint format for Mistral publisher
        # Format: https://{region}-aiplatform.googleapis.com/v1/projects/{project}/locations/{region}/publishers/mistralai/models/{model}:rawPredict
        return f"{api_base}/v1/projects/{vertex_project}/locations/{vertex_location}/publishers/mistralai/models/{model}:rawPredict"

    def _convert_url_to_data_uri_sync(self, url: str) -> str:

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Export VERTEXAI_PROJECT=<gcp-project-id>
2. Or pass vertex_project='my-project' in litellm_params / the router deployment
3. Verify with echo $VERTEXAI_PROJECT
4. In the LiteLLM proxy, add vertex_project to the deployment's litellm_params

Example fix

# before
litellm.ocr(model='vertex_ai/ocr-model', document={'type': 'image_url', 'image_url': url})

# after - either set the env var...
# export VERTEXAI_PROJECT=my-project

# ...or pass the parameter explicitly
litellm.ocr(
    model='vertex_ai/ocr-model',
    vertex_project='my-project',
    document={'type': 'image_url', 'image_url': url},
)

import os

project = os.environ.get('VERTEXAI_PROJECT')
assert project, 'VERTEXAI_PROJECT not set - vertex_ai OCR calls will fail at URL construction'

try:
    litellm.ocr(model=model, document=doc)
except ValueError as e:
    if 'vertex_project' in str(e):
        raise SystemExit('Set VERTEXAI_PROJECT or pass vertex_project')
    raise

When it happens

Trigger: Calling litellm.ocr with a vertex_ai/* model and neither a vertex_project litellm_param nor VERTEXAI_PROJECT in the environment.

Common situations: CI or container environments that copy credentials but not project env vars; assuming the project is derived from the credentials; renaming or omitting the env var.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• Missing vertex_project - Set VERTEXAI_PROJECT environment va
• vertex_project and vertex_location are required for Vertex A
• vertex_project and vertex_location are required for Vertex A
• vertex_project and vertex_location are required for Vertex A
• vertex_project and vertex_location are required for Vertex A

AI-assisted analysis of BerriAI/litellm@77b7c6c40c (2026-08-18). Data as JSON: /api/errors/b11778cf0801a4b0. Report an issue: GitHub.