{"record":{"id":"7276850668481cd2","repo":"apache/beam","slug":"either-api-url-or-model-name-must-be-provided","errorCode":null,"errorMessage":"Either api_url or model_name must be provided.","messagePattern":"Either api_url or model_name must be provided\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/ml/transforms/embeddings/huggingface.py","lineNumber":228,"sourceCode":"      api_url: API url for feature extraction. If specified, model_name will be\n        ignored. If none, the default url for feature extraction\n        will be used.\n  \"\"\"\n  def __init__(\n      self,\n      hf_token: Optional[str],\n      columns: list[str],\n      model_name: Optional[str] = None,  # example: \"sentence-transformers/all-MiniLM-l6-v2\" # pylint: disable=line-too-long\n      api_url: Optional[str] = None,\n      **kwargs,\n  ):\n    super().__init__(columns=columns, **kwargs)\n    self._authorization_token = {\"Authorization\": f\"Bearer {hf_token}\"}\n    self._model_name = model_name\n    self.hf_token = hf_token\n    if not api_url:\n      if not self._model_name:\n        raise ValueError(\"Either api_url or model_name must be provided.\")\n      self._api_url = (\n          f\"https://router.huggingface.co/hf-inference/models/{self._model_name}/pipeline/feature-extraction\"  # pylint: disable=line-too-long\n      )\n    else:\n      self._api_url = api_url\n\n    _LOGGER.info(\"HuggingFace API URL: %s\")\n\n  def get_token(self):\n    return os.environ.get('HF_TOKEN')\n\n  @property\n  def api_url(self):\n    return self._api_url\n\n  @property\n  def authorization_token(self):\n    return self._authorization_token","sourceCodeStart":210,"sourceCodeEnd":246,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/ml/transforms/embeddings/huggingface.py#L210-L246","documentation":"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.","triggerScenarios":"HuggingFaceTextEmbeddings(columns=..., hf_token=...) constructed with api_url=None and model_name=None (or model_name omitted).","commonSituations":"Copying example code that passes only hf_token and columns; refactor removing model_name assuming a default model exists.","solutions":["Pass model_name='sentence-transformers/all-MiniLM-L6-v2' (or your model) to the constructor.","Or pass the full api_url='https://router.huggingface.co/hf-inference/models/<model>/pipeline/feature-extraction'.","Verify no None/empty string is being passed for both parameters (an empty string is falsy and also triggers the model_name requirement)."],"exampleFix":"// before\nhandler = HuggingFaceTextEmbeddings(columns=['text'], hf_token=token)\n// after\nhandler = HuggingFaceTextEmbeddings(columns=['text'], hf_token=token, model_name='sentence-transformers/all-MiniLM-L6-v2')","handlingStrategy":"validation","validationCode":"if not api_url and not model_name:\n    raise ValueError('Provide api_url or model_name for HuggingFaceTextEmbeddings')","typeGuard":null,"tryCatchPattern":"try:\n    handler = HuggingFaceTextEmbeddings(columns=['text'])\nexcept ValueError as e:\n    if 'api_url or model_name' in str(e):\n        handler = HuggingFaceTextEmbeddings(columns=['text'], model_name=DEFAULT_MODEL)","preventionTips":["Always specify model_name for the remote handler","Beware empty strings being falsy too"],"tags":["python","configuration","huggingface","embeddings"],"backgroundTag":"missing-required-argument","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}