BerriAI/litellm · error · ValueError

vertex_project and vertex_location are required for Vertex A

Error message

vertex_project and vertex_location are required for Vertex AI

What it means

Imagen image generation (imagegeneration / imagen-* models) targets the predict endpoint, whose URL embeds the GCP project and region. get_complete_url resolves them from vertex_ai_project/vertex_ai_location request params, VERTEXAI_PROJECT/VERTEXAI_LOCATION (or VERTEX_LOCATION) env vars, module-level litellm.vertex_project/vertex_location, and secrets. If neither is found the call aborts with this ValueError. Note: for the image-generation handler (unlike image_edit's Imagen path), an api_base kwabypasses the check and returns early.

Source

Thrown at litellm/llms/vertex_ai/image_generation/vertex_imagen_transformation.py:140

        Get the complete URL for Vertex AI Imagen predict API
        """
        # Use the model name as provided, handling vertex_ai prefix
        model_name = model
        if model.startswith("vertex_ai/"):
            model_name = model.replace("vertex_ai/", "")

        # If a custom api_base is provided, use it directly
        # This allows users to use proxies or mock endpoints
        if api_base:
            return api_base.rstrip("/")

        # First check litellm_params (where vertex_ai_project/vertex_ai_location are passed)
        # then fall back to environment variables and other sources
        vertex_project: Final = self.safe_get_vertex_ai_project(litellm_params) or self._resolve_vertex_project()
        vertex_location: Final = self.safe_get_vertex_ai_location(litellm_params) or self._resolve_vertex_location()

        if not vertex_project or not vertex_location:
            raise ValueError("vertex_project and vertex_location are required for Vertex AI")

        base_url: Final = get_vertex_base_url(vertex_location)

        return f"{base_url}/v1/projects/{vertex_project}/locations/{vertex_location}/publishers/google/models/{model_name}:predict"

    def validate_environment(
        self,
        headers: dict,
        model: str,
        messages: list[AllMessageValues],
        optional_params: dict,
        litellm_params: dict,
        api_key: str | None = None,
        api_base: str | None = None,
    ) -> dict:
        headers = headers or {}

        # If a custom api_base is provided, skip credential validation

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Pass vertex_ai_project='my-project' and vertex_ai_location='us-central1' explicitly
2. Or export VERTEXAI_PROJECT / VERTEXAI_LOCATION in every process that calls litellm (workers included)
3. Or set litellm.vertex_project / litellm.vertex_location at startup
4. Or provide api_base, which for image generation skips project/location resolution entirely

Example fix

# before
resp = litellm.image_generation(
    model='vertex_ai/imagen-3.0-generate-002',
    prompt='a cat',
)

# after
resp = litellm.image_generation(
    model='vertex_ai/imagen-3.0-generate-002',
    prompt='a cat',
    vertex_ai_project='my-gcp-project',
    vertex_ai_location='us-central1',
)

import os

PROJECT = os.environ.get('VERTEXAI_PROJECT')
LOCATION = os.environ.get('VERTEXAI_LOCATION') or os.environ.get('VERTEX_LOCATION')
if not (PROJECT and LOCATION):
    PROJECT, LOCATION = 'my-project', 'us-central1'  # or hard fail

try:
    resp = litellm.image_generation(model='vertex_ai/imagegeneration', prompt=p)
except ValueError as e:
    if 'vertex_project and vertex_location are required' in str(e):
        raise RuntimeError('set VERTEXAI_PROJECT/VERTEXAI_LOCATION or pass them per call') from e
    raise

When it happens

Trigger: litellm.image_generation(model='vertex_ai/imagegeneration', prompt=...) with clean env and no per-call params; SDK version drift where a previously-working env-based setup stops being read; serverless deployments (Lambda/Cloud Run) that strip shell env vars.

Common situations: Moving from local dev to containerized deploys; .env files loaded by the web framework but not by the celery worker invoking litellm; multi-project GCP setups where the wrong project env var was assumed.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

• 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
• Missing vertex_project - Set VERTEXAI_PROJECT environment va
• Missing vertex_project - Set VERTEXAI_PROJECT environment va

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