apache/beam · error · ValueError

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

Error message

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

What it means

The Vertex AI multimodal embedding model only supports embedding dimensionality of 128, 256, 512, or 1408. If a `dimension` argument is passed to VertexAIImageEmbeddings with any other value (or an invalid type that isn't in the tuple), __init__ raises ValueError before building the model adapter.

Solutions

1. Set dimension to one of 128, 256, 512, or 1408.
2. Omit `dimension` entirely to use the model default (1408).
3. Align your BigQuery/Milvus vector column size with the chosen dimension.
4. Validate the config value before constructing the manager.

Example fix

// before
embedder = VertexAIImageEmbeddings(model_name='multimodalembedding@001', dimension=768)
// after
embedder = VertexAIImageEmbeddings(model_name='multimodalembedding@001', dimension=1408)

VALID_DIMS = (128, 256, 512, 1408)
assert dimension is None or dimension in VALID_DIMS, f'dimension must be one of {VALID_DIMS}'

try:
    embedder = VertexAIImageEmbeddings(model_name='multimodalembedding@001', dimension=cfg.dim)
except ValueError as e:
    logging.error('Invalid embedding dimension: %s', e)
    raise

When it happens

Trigger: VertexAIImageEmbeddings(..., dimension=768) or dimension=1024, or passing dimension copied from a text-embedding config whose model uses different sizes.

Common situations: Reusing vector DB schemas sized for text-embedding models (768/1536); typos; copying dimension from OpenAI or other providers' configs.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• at least one input column must be specified
• buffer_sec must be >= 0, got
• dimension argument must be one of 128, 256, 512, or 1408
• Expected image content in
• max_read_time_seconds must be > 0, got %r

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

Appendix: source

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

    Args:
        model_name: Name of the Vertex AI model.
        dimension: Embedding dimension. Must be one of
            128, 256, 512, or 1408.
        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 "
          "VertexAIImageEmbeddings. "
          "Please install it with "
          "`pip install google-cloud-aiplatform`")

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

    super().__init__(type_adapter=_create_image_adapter(), **kwargs)
    self.model_name = model_name
    self.dimension = dimension
    self.project = project
    self.location = location
    self.credentials = credentials

  def get_model_handler(self):
    """Returns model handler for image embedding."""
    return _VertexAIImageEmbeddingHandler(
        model_name=self.model_name,
        dimension=self.dimension,
        project=self.project,
        location=self.location,
        credentials=self.credentials,
    )

View on GitHub (pinned to 12126d8942)