{"record":{"id":"86b528eae71b6741","repo":"apache/beam","slug":"hf-token-environment-variable-not-set-please-set-the","errorCode":null,"errorMessage":"HF_TOKEN environment variable not set. Please set the environment variable or pass the token as an argument.","messagePattern":"HF_TOKEN environment variable not set\\. Please set the environment variable or pass the token as an argument\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/ml/transforms/embeddings/huggingface.py","lineNumber":179,"sourceCode":"        RunInference(\n            model_handler=_TextEmbeddingHandler(self),\n            inference_args=self.inference_args,\n        ))\n\n\nclass _InferenceAPIHandler(ModelHandler):\n  def __init__(self, config: 'InferenceAPIEmbeddings'):\n    super().__init__()\n    self._config = config\n\n  def load_model(self):\n    session = requests.Session()\n    # if the token is not provided during construction time, it might have\n    # been provided with custom container, which we can get it during runtume.\n    if not self._config.hf_token:\n      hf_token = os.environ.get(\"HF_TOKEN\")\n      if not hf_token:\n        raise ValueError(\n            'HF_TOKEN environment variable not set. '\n            'Please set the environment variable or pass the token as an '\n            'argument.')\n      session.headers.update({\"Authorization\": f\"Bearer {hf_token}\"})\n      return session\n\n    session.headers.update(self._config.authorization_token)\n    return session\n\n  def run_inference(\n      self, batch, session: requests.Session, inference_args=None):\n    response = session.post(\n        self._config.api_url,\n        headers=self._config.authorization_token,\n        json={\n            \"inputs\": batch, \"options\": inference_args\n        })\n    return response.json()","sourceCodeStart":161,"sourceCodeEnd":197,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/ml/transforms/embeddings/huggingface.py#L161-L197","documentation":"The HuggingFace embedding handler needs an access token to create authorized requests.Session for inference calls. At model-load time, if no token was supplied via the handler config and the HF_TOKEN environment variable is also absent, it raises ValueError because unauthenticated requests to HuggingFace inference endpoints will fail.","triggerScenarios":"Calling load_model on HuggingFaceTextEmbeddings (remote inference API handler) when the handler was constructed without hf_token and the runtime environment (e.g. Beam worker container) does not define HF_TOKEN.","commonSituations":"Running a Beam pipeline on Dataflow/Flink where the local HF_TOKEN env var was set only on the dev machine, not passed via worker environment options; forgetting to pass hf_token to the handler constructor.","solutions":["Set the HF_TOKEN environment variable in the runtime environment (export HF_TOKEN=hf_xxx, or pass --env or worker environment variables in your runner).","Pass the token explicitly: HuggingFaceTextEmbeddings(columns=['text'], hf_token='hf_xxx').","For containers, bake the token into the custom container env or fetch it from a secret manager at pipeline setup."],"exampleFix":"// before\nhandler = HuggingFaceTextEmbeddings(columns=['text'])\n// after\nhandler = HuggingFaceTextEmbeddings(columns=['text'], hf_token=os.environ.get('HF_TOKEN'))","handlingStrategy":"validation","validationCode":"import os\nassert os.environ.get('HF_TOKEN') or hf_token, \"HF_TOKEN env var or hf_token argument required\"","typeGuard":"def has_hf_token():\n    return bool(os.environ.get('HF_TOKEN'))","tryCatchPattern":"try:\n    session = handler.load_model()\nexcept ValueError as e:\n    if 'HF_TOKEN' in str(e):\n        os.environ['HF_TOKEN'] = fetch_token_from_secret_manager()\n        session = handler.load_model()\n    else:\n        raise","preventionTips":["Set HF_TOKEN in all runtime environments, including remote runners","Pass hf_token explicitly in the handler constructor","Inject secrets via runner environment options or a secret manager"],"tags":["python","authentication","environment-variable","huggingface","embeddings"],"backgroundTag":"missing-env-var","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"}