apache/beam · error · ImportError

vertexai is required to use VertexAITextEmbeddings. Please i

Error message

vertexai is required to use VertexAITextEmbeddings. Please install it with `pip install google-cloud-aiplatform`

What it means

VertexAITextEmbeddings.__init__ raises this ImportError when the vertexai module (from google-cloud-aiplatform) is not importable. The module imports vertexai in a guarded try/except (None on failure) and the constructor fails fast with a pip install hint. This class calls Vertex AI embedding models, which require the aiplatform SDK client.

Source

Thrown at sdks/python/apache_beam/ml/rag/embeddings/vertex_ai.py:74

      project: Optional[str] = None,
      location: Optional[str] = None,
      credentials: Optional[Credentials] = None,
      **kwargs):
    """Utilizes Vertex AI text embeddings for semantic search and RAG
    pipelines.

    Args:
        model_name: Name of the Vertex AI text embedding model
        title: Optional title for the text content
        task_type: Task type for embeddings (default: RETRIEVAL_DOCUMENT)
        project: GCP project ID
        location: GCP location
        credentials: Optional GCP credentials
        **kwargs: Additional arguments passed to
            :class:`~apache_beam.ml.transforms.base.EmbeddingsManager`.
    """
    if not vertexai:
      raise ImportError(
          "vertexai is required to use VertexAITextEmbeddings. "
          "Please install it with `pip install google-cloud-aiplatform`")

    super().__init__(type_adapter=create_text_adapter(), **kwargs)
    self.model_name = model_name
    self.title = title
    self.task_type = task_type
    self.project = project
    self.location = location
    self.credentials = credentials

  def get_model_handler(self):
    """Returns model handler configured with RAG adapter."""
    return _VertexAITextEmbeddingHandler(
        model_name=self.model_name,
        title=self.title,
        task_type=self.task_type,
        project=self.project,

View on GitHub (pinned to 12126d8942)

Solutions

1. Install the dependency: pip install google-cloud-aiplatform.
2. Install Beam with the GCP extra: pip install apache_beam[gcp], and ship it via --requirements_file or setup_file to remote runners.
3. Resolve dependency conflicts if google-cloud-aiplatform fails to install (pip check).

Example fix

// before
embedder = VertexAITextEmbeddings(model_name='textembedding-gecko@003', project='my-proj')

// after
# terminal: pip install google-cloud-aiplatform
embedder = VertexAITextEmbeddings(model_name='textembedding-gecko@003', project='my-proj')

import importlib.util

def vertexai_available() -> bool:
    return importlib.util.find_spec('google.cloud.aiplatform') is not None

try:
    embedder = VertexAITextEmbeddings(model_name='textembedding-gecko@003', project='my-proj')
except ImportError:
    logging.error('Install: pip install google-cloud-aiplatform (or apache_beam[gcp])')
    raise

When it happens

Trigger: Constructing VertexAITextEmbeddings(model_name=..., project=..., location=...) without google-cloud-aiplatform installed; Beam worker environments missing the package because it wasn't in the requirements file (it is included in the apache_beam[gcp] extra only if that extra was actually installed).

Common situations: Local dev environment with plain apache_beam install; Dataflow workers launched without the gcp extra; dependency conflicts where google-cloud-aiplatform failed to install due to version pins.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

• langchain is required to use LangChainChunkerPlease install
• sentence-transformers is required to use HuggingfaceTextEmbe
• sentence-transformers is required to use HuggingfaceImageEmb
• Pillow is required to use HuggingfaceImageEmbeddings. Please
• query.project cannot be empty

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/3ed290a6f5e0ef16. Report an issue: GitHub.