apache/beam · error · ValueError

dimension argument must be one of 128, 256, 512, or 1408

Error message

dimension argument must be one of 128, 256, 512, or 1408

What it means

VertexAIImageEmbeddings only supports the fixed output dimensions offered by the Vertex multimodal embedding model: 128, 256, 512, or 1408. Passing any other dimension (when not None) raises ValueError at construction.

Solutions

Set dimension to one of 128, 256, 512, or 1408.
Pass dimension=None to use the model default (1408).
Check the model version docs; older multimodal models may only support 1408.

Example fix

// before
handler = VertexAIImageEmbeddings(columns=['image'], dimension=768)
// after
handler = VertexAIImageEmbeddings(columns=['image'], dimension=1408)

Defensive patterns

Strategy: validation

Validate before calling

if dimension is not None and dimension not in (128, 256, 512, 1408):
    raise ValueError('dimension must be one of 128, 256, 512, 1408')

Try / catch

try:
    handler = VertexAIImageEmbeddings(columns=['image'], dimension=dim)
except ValueError as e:
    if 'dimension' in str(e):
        handler = VertexAIImageEmbeddings(columns=['image'], dimension=None)

Prevention

Use dimension=None unless reduced dims are required
Keep allowed dims in a shared constant

When it happens

Trigger: VertexAIImageEmbeddings(columns=..., dimension=768) or any dimension outside {128, 256, 512, 1408}.

Common situations: Reusing a dimension value chosen for another embedding model (e.g. 768 for BERT-style models) when switching to Vertex AI image embeddings.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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

Appendix: source

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

    for use.

    Args:
      model_name: The name of the Vertex AI Multi-Modal Embedding model.
      columns: The columns containing the image to be embedded.
      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.
      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
    super().__init__(columns=columns, **kwargs)

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

  def get_ptransform_for_processing(self, **kwargs) -> beam.PTransform:
    return RunInference(
        model_handler=_ImageEmbeddingHandler(self),
        inference_args=self.inference_args)

View on GitHub (pinned to 12126d8942)