BerriAI/litellm · error · ValueError

Vertex AI project ID is required. Please set 'VERTEXAI_PROJE

Error message

Vertex AI project ID is required. Please set 'VERTEXAI_PROJECT', 'litellm.vertex_project', or pass 'vertex_project' parameter

What it means

ValueError raised while constructing the Vertex AI Discovery Engine rerank URL when no project ID can be resolved. The handler first extracts the project from the supplied credentials (via _ensure_access_token), then falls back to the VERTEXAI_PROJECT environment variable and finally litellm.vertex_project; if all are empty the rankingConfigs URL cannot be built.

Source

Thrown at litellm/llms/vertex_ai/rerank/transformation.py:65

        params: Final = optional_params or {}

        # Get credentials to extract project ID if needed
        vertex_credentials: Final = self.safe_get_vertex_ai_credentials(params.copy())
        vertex_project = self.safe_get_vertex_ai_project(params.copy())

        # Use _ensure_access_token to extract project_id from credentials
        # This is the same method used in vertex embeddings
        _, vertex_project = self._ensure_access_token(
            credentials=vertex_credentials,
            project_id=vertex_project,
            custom_llm_provider="vertex_ai",
        )

        # Fallback to environment or litellm config
        project_id: Final = vertex_project or get_secret_str("VERTEXAI_PROJECT") or litellm.vertex_project

        if not project_id:
            raise ValueError(
                "Vertex AI project ID is required. Please set 'VERTEXAI_PROJECT', 'litellm.vertex_project', or pass 'vertex_project' parameter"
            )

        return f"https://discoveryengine.googleapis.com/v1/projects/{project_id}/locations/global/rankingConfigs/default_ranking_config:rank"

    def validate_environment(
        self,
        headers: dict,
        model: str,
        api_key: str | None = None,
        optional_params: dict | None = None,
    ) -> dict:
        """
        Validate and set up authentication for Vertex AI Discovery Engine API
        """
        # Get credentials and project info from optional_params (which contains vertex_credentials, etc.)
        litellm_params: Final = optional_params.copy() if optional_params else {}
        vertex_credentials: Final = self.safe_get_vertex_ai_credentials(litellm_params)

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Pass vertex_project='my-project' in the rerank call / router deployment
2. Or export VERTEXAI_PROJECT=my-project
3. Or set litellm.vertex_project='my-project' globally
4. If using service-account credentials, use one whose JSON includes project_id so it is auto-extracted

Example fix

# before
litellm.rerank(model='vertex_ai/semantic-ranker', query='q', documents=docs)

# after
litellm.rerank(
    model='vertex_ai/semantic-ranker',
    query='q',
    documents=docs,
    vertex_project='my-project',
)

import os
import litellm

project = os.environ.get('VERTEXAI_PROJECT') or litellm.vertex_project
assert project, 'vertex_ai rerank needs vertex_project / VERTEXAI_PROJECT / litellm.vertex_project'

try:
    resp = litellm.rerank(model=model, query=q, documents=docs)
except ValueError as e:
    if 'project ID is required' in str(e):
        raise SystemExit('Set VERTEXAI_PROJECT or pass vertex_project')
    raise

When it happens

Trigger: Calling litellm.rerank with a vertex_ai/... model when the credentials carry no project, VERTEXAI_PROJECT is unset, and litellm.vertex_project was never assigned.

Common situations: Using access-token-only auth with no project attached; env var missing in the deployed runtime; multi-project service accounts where the token is project-less.

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

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

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