apache/beam · error · ValueError

Either api_url or model_name must be provided.

Error message

Either api_url or model_name must be provided.

What it means

The remote HuggingFace inference handler needs an endpoint: either an explicit api_url or a model_name from which the default feature-extraction URL is derived. If both are missing/None at construction, ValueError is raised because no inference endpoint can be built.

Solutions

  1. Pass model_name='sentence-transformers/all-MiniLM-L6-v2' (or your model) to the constructor.
  2. Or pass the full api_url='https://router.huggingface.co/hf-inference/models/<model>/pipeline/feature-extraction'.
  3. Verify no None/empty string is being passed for both parameters (an empty string is falsy and also triggers the model_name requirement).

Example fix

// before
handler = HuggingFaceTextEmbeddings(columns=['text'], hf_token=token)
// after
handler = HuggingFaceTextEmbeddings(columns=['text'], hf_token=token, model_name='sentence-transformers/all-MiniLM-L6-v2')
Defensive patterns

Strategy: validation

Validate before calling

if not api_url and not model_name:
    raise ValueError('Provide api_url or model_name for HuggingFaceTextEmbeddings')

Try / catch

try:
    handler = HuggingFaceTextEmbeddings(columns=['text'])
except ValueError as e:
    if 'api_url or model_name' in str(e):
        handler = HuggingFaceTextEmbeddings(columns=['text'], model_name=DEFAULT_MODEL)

Prevention

When it happens

Trigger: HuggingFaceTextEmbeddings(columns=..., hf_token=...) constructed with api_url=None and model_name=None (or model_name omitted).

Common situations: Copying example code that passes only hf_token and columns; refactor removing model_name assuming a default model exists.

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/7276850668481cd2. Report an issue: GitHub.

Appendix: source

Thrown at sdks/python/apache_beam/ml/transforms/embeddings/huggingface.py:228

      api_url: API url for feature extraction. If specified, model_name will be
        ignored. If none, the default url for feature extraction
        will be used.
  """
  def __init__(
      self,
      hf_token: Optional[str],
      columns: list[str],
      model_name: Optional[str] = None,  # example: "sentence-transformers/all-MiniLM-l6-v2" # pylint: disable=line-too-long
      api_url: Optional[str] = None,
      **kwargs,
  ):
    super().__init__(columns=columns, **kwargs)
    self._authorization_token = {"Authorization": f"Bearer {hf_token}"}
    self._model_name = model_name
    self.hf_token = hf_token
    if not api_url:
      if not self._model_name:
        raise ValueError("Either api_url or model_name must be provided.")
      self._api_url = (
          f"https://router.huggingface.co/hf-inference/models/{self._model_name}/pipeline/feature-extraction"  # pylint: disable=line-too-long
      )
    else:
      self._api_url = api_url

    _LOGGER.info("HuggingFace API URL: %s")

  def get_token(self):
    return os.environ.get('HF_TOKEN')

  @property
  def api_url(self):
    return self._api_url

  @property
  def authorization_token(self):
    return self._authorization_token

View on GitHub (pinned to 12126d8942)