apache/beam · error · ValueError

task_type must be one of

Error message

task_type must be one of {TASK_TYPE_INPUTS}, got {task_type}

What it means

VertexAITextEmbeddings validates that task_type is a member of the TASK_TYPE_INPUTS set of supported Vertex AI embedding task types. An unknown or misspelled task_type is rejected at construction with ValueError before any API call is made.

Solutions

Use a valid task_type such as 'RETRIEVAL_QUERY', 'RETRIEVAL_DOCUMENT', 'SEMANTIC_SIMILARITY', 'CLASSIFICATION', 'CLUSTERING' (match the TASK_TYPE_INPUTS set exactly, uppercase).
Import TASK_TYPE_INPUTS from apache_beam.ml.transforms.embeddings.vertex_ai and pick from it programmatically.
Omit task_type if a default is acceptable.

Example fix

// before
handler = VertexAITextEmbeddings(columns=['text'], task_type='retrieval_query')
// after
handler = VertexAITextEmbeddings(columns=['text'], task_type='RETRIEVAL_QUERY')

Defensive patterns

Strategy: validation

Validate before calling

from apache_beam.ml.transforms.embeddings.vertex_ai import TASK_TYPE_INPUTS
assert task_type in TASK_TYPE_INPUTS, f'{task_type} not in {TASK_TYPE_INPUTS}'

Try / catch

try:
    handler = VertexAITextEmbeddings(columns=['text'], task_type=my_task)
except ValueError as e:
    if 'task_type' in str(e):
        handler = VertexAITextEmbeddings(columns=['text'], task_type=list(TASK_TYPE_INPUTS)[0])

Prevention

Pick task_type from TASK_TYPE_INPUTS, never hardcode
Keep enum values uppercase

When it happens

Trigger: Constructing VertexAITextEmbeddings(model_name=..., task_type='embedding' or any value not in TASK_TYPE_INPUTS).

Common situations: Typos like 'retrival_query' vs 'RETRIEVAL_QUERY'; copying task_type values from another embedding provider (e.g. OpenAI) that Vertex AI doesn't accept; lowercasing a valid enum value.

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

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

Appendix: source

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


class _VertexAITextEmbeddingHandler(RemoteModelHandler):
  """
  Note: Intended for internal use and guarantees no backwards compatibility.
  """
  def __init__(
      self,
      model_name: str,
      title: Optional[str] = None,
      task_type: str = DEFAULT_TASK_TYPE,
      project: Optional[str] = None,
      location: Optional[str] = None,
      credentials: Optional[Credentials] = None,
      **kwargs):
    vertexai.init(project=project, location=location, credentials=credentials)
    self.model_name = model_name
    if task_type not in TASK_TYPE_INPUTS:
      raise ValueError(
          f"task_type must be one of {TASK_TYPE_INPUTS}, got {task_type}")
    self.task_type = task_type
    self.title = title

    super().__init__(
        namespace='VertexAITextEmbeddingHandler',
        retry_filter=_retry_on_appropriate_gcp_error,
        **kwargs)

  def request(
      self,
      batch: Sequence[str],
      model: TextEmbeddingModel,
      inference_args: Optional[dict[str, Any]] = None):
    embeddings = []
    batch_size = _BATCH_SIZE
    for i in range(0, len(batch), batch_size):
      text_batch_strs = batch[i:i + batch_size]

View on GitHub (pinned to 12126d8942)