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

For Gemini-based image generation (e.g. gemini-2.5-flash-image style models) on Vertex AI, litellm must construct .../projects/{project}/locations/{location}/publishers/google/models/{model}:generateContent. Project and location are resolved from vertex_ai_project/vertex_ai_location params, VERTEXAI_PROJECT/VERTEXAI_LOCATION env vars, module-level litellm.vertex_project/vertex_location, and secrets; if both remain unset this ValueError raises pre-flight. An api_base kwarg short-circuits resolution and is used verbatim.

Source

Thrown at litellm/llms/vertex_ai/image_generation/vertex_gemini_transformation.py:167

        Get the complete URL for Vertex AI Gemini generateContent 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}:generateContent"

    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 and vertex_ai_location on the call
2. Or export VERTEXAI_PROJECT / VERTEXAI_LOCATION where the process runs
3. Or set litellm.vertex_project / litellm.vertex_location once at app startup
4. For gateway/proxy setups, pass api_base to skip resolution

Example fix

# before
resp = litellm.image_generation(
    model='vertex_ai/gemini-2.5-flash-image',
    prompt='a cat wearing sunglasses',
)  # raises in env without VERTEXAI_PROJECT/LOCATION

# after
resp = litellm.image_generation(
    model='vertex_ai/gemini-2.5-flash-image',
    prompt='a cat wearing sunglasses',
    vertex_ai_project='my-gcp-project',
    vertex_ai_location='us-central1',
)

import os

assert os.environ.get('VERTEXAI_PROJECT') and (
    os.environ.get('VERTEXAI_LOCATION') or os.environ.get('VERTEX_LOCATION')
), 'set vertex project/location before image generation calls'

try:
    resp = litellm.image_generation(model='vertex_ai/gemini-2.5-flash-image', prompt=p)
except ValueError as e:
    if 'vertex_project and vertex_location are required' in str(e):
        raise RuntimeError('missing Vertex config — pass vertex_ai_project/location') from e
    raise

When it happens

Trigger: litellm.image_generation(model='vertex_ai/gemini-2.5-flash-image', prompt=...) in an environment with no VERTEXAI_PROJECT/VERTEXAI_LOCATION and no per-call project/location; works on a dev laptop (env set in .bashrc) but fails in CI/docker where the env is clean.

Common situations: Env vars not propagated into systemd/docker/proxy processes; wrong env var names (GOOGLE_CLOUD_PROJECT is not consulted here); teams relying on ADC credentials and forgetting the URL also needs project/region.

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/8480bbed37563853. Report an issue: GitHub.