BerriAI/litellm · error · ValueError

gcs_bucket is required for Vertex AI RAG ingestion. Set via

Error message

gcs_bucket is required for Vertex AI RAG ingestion. Set via vector_store config or GCS_BUCKET_NAME env var.

What it means

ValueError raised in VertexRAGIngestion.__init__ when no GCS bucket is configured. Vertex RAG ingestion uploads each file to Google Cloud Storage before importing it into the RAG corpus, so a bucket is resolved from vector_store config 'gcs_bucket' or the GCS_BUCKET_NAME environment variable and must be present.

Source

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

        # Get corpus ID (required for Vertex AI)
        self.corpus_id = self.vector_store_config.get("vector_store_id")
        if not self.corpus_id:
            raise ValueError(
                "vector_store_id (corpus ID) is required for Vertex AI RAG ingestion. "
                "Please provide an existing RAG corpus ID."
            )

        # GCP config
        self.vertex_project = self.vector_store_config.get("vertex_project") or get_secret_str("VERTEXAI_PROJECT")
        self.vertex_location = (
            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}"

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Set gcs_bucket='my-bucket' in the vector_store config, or export GCS_BUCKET_NAME=my-bucket
2. Create the bucket first if needed: gcloud storage buckets create gs://my-bucket
3. Grant the credentials storage.objects.create on that bucket - otherwise init passes but the later upload step fails

Example fix

# before
vector_store_config = {'vector_store_id': 'corpus-123', 'vertex_project': 'my-project'}

# after
vector_store_config = {
    'vector_store_id': 'corpus-123',
    'vertex_project': 'my-project',
    'gcs_bucket': 'my-rag-uploads',  # or: export GCS_BUCKET_NAME=my-rag-uploads
}

import os

cfg = get_vector_store_config()
bucket = cfg.get('gcs_bucket') or os.environ.get('GCS_BUCKET_NAME')
assert bucket, 'gcs_bucket or GCS_BUCKET_NAME is required for vertex_ai RAG ingestion'

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

When it happens

Trigger: Building a Vertex RAG ingestion job whose vector_store config omits gcs_bucket and whose process environment lacks GCS_BUCKET_NAME.

Common situations: Teams that already created a corpus but forgot the upload bucket; env var named differently (GCS_BUCKET vs GCS_BUCKET_NAME); bucket exists in another project/account.

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

• vector_store_id (corpus ID) is required for Vertex AI RAG in
• vertex_project is required for Vertex AI RAG ingestion. Set
• Failed to import file into RAG corpus: {e}
• vertex_project and vertex_location are required for Vertex A
• vertex_project and vertex_location are required for Vertex A

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