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

Vertex AI Gemini image edit builds its endpoint URL as {base}/v1/projects/{project}/locations/{location}/publishers/google/models/{model}:generateContent, so it must know your GCP project and region. Litellm resolves them from per-call params (vertex_ai_project / vertex_ai_location), instance attributes, VERTEXAI_PROJECT / VERTEXAI_LOCATION env vars, module-level litellm.vertex_project / litellm.vertex_location, and secret stores. If both project and location are still unresolved, this ValueError is raised before any HTTP request. Supplying api_base bypasses the check entirely.

Source

Thrown at litellm/llms/vertex_ai/image_edit/vertex_gemini_transformation.py:140

        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 transform_image_edit_request(
        self,
        model: str,
        prompt: str | None,
        image: FileTypes | None,
        image_edit_optional_request_params: dict[str, Any],
        litellm_params: GenericLiteLLMParams,
        headers: dict,
    ) -> tuple[dict[str, Any], RequestFiles | None]:
        inline_parts: Final = self._prepare_inline_image_parts(image) if image else []
        if not inline_parts:
            raise ValueError("Vertex AI Gemini image edit requires at least one image.")

View on GitHub (pinned to 77b7c6c40c)

Solutions

Pass vertex_ai_project='my-project' and vertex_ai_location='us-central1' directly on the litellm.image_edit() call
Or export VERTEXAI_PROJECT and VERTEXAI_LOCATION in the process environment
Or set module-level defaults: litellm.vertex_project='my-project'; litellm.vertex_location='us-central1'
For proxies/mocks, pass api_base='https://my-proxy/...' which skips project/location resolution and uses the URL as-is

Example fix

# before
resp = litellm.image_edit(
    model='vertex_ai/gemini-2.5-flash-image',
    prompt='add a red hat',
    image=open('cat.png', 'rb'),
)  # raises: no project/location

# after
resp = litellm.image_edit(
    model='vertex_ai/gemini-2.5-flash-image',
    prompt='add a red hat',
    image=open('cat.png', 'rb'),
    vertex_ai_project='my-gcp-project',
    vertex_ai_location='us-central1',
)

Defensive patterns

Strategy: validation

Validate before calling

import os

VERTEX_PROJECT = os.environ.get('VERTEXAI_PROJECT')
VERTEX_LOCATION = os.environ.get('VERTEXAI_LOCATION')

if not VERTEX_PROJECT or not VERTEX_LOCATION:
    raise RuntimeError('Set VERTEXAI_PROJECT and VERTEXAI_LOCATION (or pass vertex_ai_project/vertex_ai_location)')

Try / catch

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

Prevention

Pass vertex_ai_project and vertex_ai_location explicitly on every vertex_ai call instead of relying on env
Assert required env vars at process startup, not at request time
Remember api_base bypasses project/location resolution — useful for mocks and proxies

When it happens

Trigger: litellm.image_edit(model='vertex_ai/gemini-2.5-flash-image', prompt=..., image=f) with no vertex_ai_project/vertex_ai_location kwargs, no VERTEXAI_PROJECT/VERTEXAI_LOCATION env vars, and no api_base. Common in fresh CI runners or containers where only GOOGLE_APPLICATION_CREDENTIALS is set (credentials are enough for the token, not for the URL).

Common situations: Auth succeeds via Application Default Credentials but project/location were never configured; setting GOOGLE_CLOUD_PROJECT instead of VERTEXAI_PROJECT (the former is not read here); passing the wrong kwarg name such as vertex_project instead of vertex_ai_project; env vars set in a shell but not in the server/proxy process.

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

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