BerriAI/litellm · error · ValueError

vertex_project is required for Vertex AI RAG ingestion. Set

Error message

vertex_project is required for Vertex AI RAG ingestion. Set via vector_store config or VERTEXAI_PROJECT env var.

What it means

ValueError raised in VertexRAGIngestion.__init__ when vertex_project cannot be resolved from the vector_store config or the VERTEXAI_PROJECT environment variable. The project is required to build corpus resource names like projects/{project}/locations/{location}/ragCorpora/{id}, so init fails fast before any GCP call is made.

Source

Thrown at litellm/llms/vertex_ai/rag_engine/ingestion.py:102

            self.vector_store_config.get("vertex_location") or get_secret_str("VERTEXAI_LOCATION") or "us-central1"
        )
        self.vertex_credentials = self.vector_store_config.get("vertex_credentials")

        # GCS bucket for file uploads
        self.gcs_bucket = self.vector_store_config.get("gcs_bucket") or os.environ.get("GCS_BUCKET_NAME")
        if not self.gcs_bucket:
            raise ValueError(
                "gcs_bucket is required for Vertex AI RAG ingestion. "
                "Set via vector_store config or GCS_BUCKET_NAME env var."
            )

        # Import settings
        self.wait_for_import = self.vector_store_config.get("wait_for_import", True)
        self.import_timeout = _get_int(self.vector_store_config.get("import_timeout"), 600)

        # Validate required config
        if not self.vertex_project:
            raise ValueError(
                "vertex_project is required for Vertex AI RAG ingestion. "
                "Set via vector_store config or VERTEXAI_PROJECT env var."
            )

    def _get_corpus_name(self) -> str:
        """Get full corpus resource name."""
        return f"projects/{self.vertex_project}/locations/{self.vertex_location}/ragCorpora/{self.corpus_id}"

    async def _upload_file_to_gcs(
        self,
        file_content: bytes,
        filename: str,
        content_type: str,
    ) -> str:
        """
        Upload file to GCS using litellm.files.acreate_file.

        Returns:

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Set vertex_project='my-project' in the vector_store config, or export VERTEXAI_PROJECT=my-project
2. Verify with echo $VERTEXAI_PROJECT
3. Prefer explicit config over env in multi-project setups to avoid importing into the wrong project

Example fix

# before
vector_store_config = {'vector_store_id': 'corpus-123', 'gcs_bucket': 'my-bucket'}

# after
vector_store_config = {
    'vector_store_id': 'corpus-123',
    'gcs_bucket': 'my-bucket',
    'vertex_project': 'my-project',  # or: export VERTEXAI_PROJECT=my-project
}

import os

cfg = get_vector_store_config()
project = cfg.get('vertex_project') or os.environ.get('VERTEXAI_PROJECT')
assert project, 'vertex_project or VERTEXAI_PROJECT is required for vertex_ai RAG ingestion'

try:
    ingestion = VertexRAGIngestion(ingest_options=opts, router=router)
except ValueError as e:
    if 'vertex_project' in str(e):
        raise SystemExit('Set vertex_project in config or export VERTEXAI_PROJECT')
    raise

When it happens

Trigger: RAG ingestion config lacking vertex_project while VERTEXAI_PROJECT is unset in the process environment.

Common situations: Credentials JSON present but the project not configured anywhere; env vars not carried into containers or serverless runtimes; multi-project confusion.

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/9d88c876d935ed46. Report an issue: GitHub.