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 DeepSeek 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 the VERTEXAI_PROJECT environment variable); if nothing is found, the projects/{project}/... URL cannot be constructed and the call aborts before any request is sent.

Source

Thrown at litellm/llms/vertex_ai/ocr/deepseek_transformation.py:113

        Get complete URL for Vertex AI DeepSeek OCR endpoint.

        Args:
            api_base: Vertex AI API base URL (optional)
            model: Model name (e.g., "deepseek-ai/deepseek-ocr-maas")
            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 = "https://aiplatform.googleapis.com"

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

        return f"{api_base}/v1/projects/{vertex_project}/locations/{vertex_location}/endpoints/openapi/chat/completions"

    def transform_ocr_request(
        self,
        model: str,

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Export VERTEXAI_PROJECT=<gcp-project-id> in the environment of the process calling litellm
2. Or pass vertex_project='my-project' in the request's litellm_params / router deployment litellm_params
3. Verify it resolves: echo $VERTEXAI_PROJECT
4. If using the LiteLLM proxy, set vertex_project in the model deployment config

Example fix

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

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

# ...or pass the parameter explicitly
litellm.ocr(
    model='vertex_ai/deepseek-ai/deepseek-ocr',
    vertex_project='my-project',
    document={'type': 'document_url', 'document_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 the Vertex AI OCR handler with a 'vertex_ai/deepseek-ai/deepseek-ocr' style model without a vertex_project litellm_param and without VERTEXAI_PROJECT set in the environment.

Common situations: Container deployments where only GOOGLE_APPLICATION_CREDENTIALS is set - credentials alone do not supply the project for this handler; assuming the project is inferred from the credentials JSON; typo in the env var name.

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/9d3975bfe088ac4e. Report an issue: GitHub.