apache/beam · error · ValueError

at least one input column must be specified

Error message

at least one input column must be specified

What it means

The Vertex AI multimodal embeddings handler requires at least one of image_column, video_column, or text_column to be specified, since it must know which input fields to embed. Supplying none raises ValueError in __init__.

Solutions

  1. Pass at least one of image_column='img', video_column='vid', or text_column='txt' to the constructor.
  2. If you only embed text, use the text-only handler instead.
  3. Ensure the column names match your PCollection schema field names.

Example fix

// before
handler = VertexAIMultimodalEmbeddings(columns=['data'])
// after
handler = VertexAIMultimodalEmbeddings(columns=['data'], image_column='image', text_column='caption')
Defensive patterns

Strategy: validation

Validate before calling

if not (image_column or video_column or text_column):
    raise ValueError('specify at least one of image_column, video_column, text_column')

Try / catch

try:
    handler = MultimodalHandler(columns=cols)
except ValueError as e:
    if 'at least one input column' in str(e):
        handler = MultimodalHandler(columns=cols, text_column='text')

Prevention

When it happens

Trigger: Constructing the multimodal handler with image_column=None, video_column=None, and text_column=None (or omitted).

Common situations: Migrating from the image-only or text-only handler and forgetting that the multimodal one requires explicit column names; passing columns= only and assuming it maps to inputs.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at sdks/python/apache_beam/ml/transforms/embeddings/vertex_ai.py:495

      dimension: The length of the embedding vector to generate. Must be one of
        128, 256, 512, or 1408. If not set, Vertex AI's default value is 1408.
        If submitting video content, dimension *musst* be 1408.
      project: The default GCP project for API calls.
      location: The default location for API calls.
      credentials: Custom credentials for API calls.
        Defaults to environment credentials.
    """
    self.model_name = model_name
    self.project = project
    self.location = location
    self.credentials = credentials
    self.kwargs = kwargs
    if dimension is not None and dimension not in (128, 256, 512, 1408):
      raise ValueError(
          "dimension argument must be one of 128, 256, 512, or 1408")
    self.dimension = dimension
    if not image_column and not video_column and not text_column:
      raise ValueError("at least one input column must be specified")
    if video_column is not None and dimension != 1408:
      raise ValueError(
          "Vertex AI does not support custom dimensions for video input, want dimension = 1408, got ",
          dimension)
    self.type_adapter = _create_multimodal_dict_adapter(
        image_column=image_column,
        video_column=video_column,
        text_column=text_column)
    super().__init__(type_adapter=self.type_adapter, **kwargs)

  def get_model_handler(self) -> ModelHandler:
    return _VertexAIMultiModalEmbeddingHandler(
        model_name=self.model_name,
        dimension=self.dimension,
        project=self.project,
        location=self.location,
        credentials=self.credentials,
        **self.kwargs)

View on GitHub (pinned to 12126d8942)