BerriAI/litellm · error · ValueError

vertex_project is required for Vertex Agent Engine. Set via

Error message

vertex_project is required for Vertex Agent Engine. Set via litellm_params['vertex_project'] or VERTEXAI_PROJECT env var.

What it means

Vertex Agent Engine URL builder guard: the GCP project could not be resolved from litellm_params['vertex_project'] or the VERTEXAI_PROJECT env var, so the required projects/... URL path cannot be constructed.

Source

Thrown at litellm/llms/vertex_ai/agent_engine/transformation.py:127

        stream: bool | None = None,
    ) -> str:
        """
        Get the complete URL for the request.

        For Vertex Agent Engine:
        - Non-streaming: :query endpoint (for session management)
        - Streaming: :streamQuery endpoint (for actual queries)
        """
        resource_path, engine_id = self._parse_model_string(model)

        # Get project and location from litellm_params or environment
        vertex_project: Final = self.safe_get_vertex_ai_project(litellm_params)
        vertex_location: Final = self.safe_get_vertex_ai_location(litellm_params) or "us-central1"

        # Build the full resource path if only engine_id was provided
        if not resource_path.startswith("projects/"):
            if not vertex_project:
                raise ValueError(
                    "vertex_project is required for Vertex Agent Engine. "
                    "Set via litellm_params['vertex_project'] or VERTEXAI_PROJECT env var."
                )
            resource_path = f"projects/{vertex_project}/locations/{vertex_location}/reasoningEngines/{engine_id}"

        base_url: Final = get_vertex_base_url(vertex_location)

        # Always use :streamQuery endpoint for actual queries
        # The :query endpoint only supports session management methods
        # (create_session, get_session, list_sessions, delete_session, etc.)
        endpoint: Final = f"{base_url}/v1beta1/{resource_path}:streamQuery"

        verbose_logger.debug("Vertex Agent Engine URL: %s", endpoint)
        return endpoint

    def _get_auth_headers(
        self,
        optional_params: dict,

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Set VERTEXAI_PROJECT environment variable.
2. Or pass vertex_project in litellm_params.

Example fix

os.environ["VERTEXAI_PROJECT"] = "my-gcp-project"

When it happens

Trigger: Triggered when calling Vertex Agent Engine without vertex_project in litellm_params and VERTEXAI_PROJECT unset.

Common situations: See trigger scenarios.

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