{"record":{"id":"9b2f109f10cbdf76","repo":"apache/beam","slug":"sentence-transformers-is-required-to-use","errorCode":null,"errorMessage":"sentence-transformers is required to use HuggingfaceTextEmbeddings.Please install it with using `pip install sentence-transformers`.","messagePattern":"sentence-transformers is required to use HuggingfaceTextEmbeddings\\.Please install it with using `pip install sentence-transformers`\\.","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/ml/rag/embeddings/huggingface.py","lineNumber":70,"sourceCode":"        model_name: Name of the sentence-transformers model to use.\n        max_seq_length: Maximum sequence length for the model.\n        **kwargs: Additional arguments passed to\n            :class:`~apache_beam.ml.transforms.base.EmbeddingsManager`,\n            including:\n\n            - ``load_model_args``: dict passed to\n              ``SentenceTransformer()`` constructor\n              (e.g. ``device``, ``cache_folder``).\n            - ``min_batch_size`` / ``max_batch_size``:\n              Control batching for inference.\n            - ``large_model``: If True, share the model\n              across processes to reduce memory usage.\n            - ``inference_args``: dict passed to\n              ``model.encode()``\n              (e.g. ``normalize_embeddings``).\n    \"\"\"\n    if not SentenceTransformer:\n      raise ImportError(\n          \"sentence-transformers is required to use \"\n          \"HuggingfaceTextEmbeddings.\"\n          \"Please install it with using `pip install sentence-transformers`.\")\n    super().__init__(type_adapter=create_text_adapter(), **kwargs)\n    self.model_name = model_name\n    self.max_seq_length = max_seq_length\n    self.model_class = SentenceTransformer\n\n  def get_model_handler(self):\n    \"\"\"Returns model handler configured with RAG adapter.\"\"\"\n    return _SentenceTransformerModelHandler(\n        model_class=self.model_class,\n        max_seq_length=self.max_seq_length,\n        model_name=self.model_name,\n        load_model_args=self.load_model_args,\n        min_batch_size=self.min_batch_size,\n        max_batch_size=self.max_batch_size,\n        large_model=self.large_model)","sourceCodeStart":52,"sourceCodeEnd":88,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/ml/rag/embeddings/huggingface.py#L52-L88","documentation":"HuggingfaceTextEmbeddings.__init__ raises this ImportError when the sentence-transformers package is not installed. The module imports SentenceTransformer in a guarded try/except (leaving it None), and the constructor fails fast with a pip install hint. This class embeds text via SentenceTransformer models, which cannot function without the library.","triggerScenarios":"Constructing HuggingfaceTextEmbeddings(model_name=...) in an environment where `pip install sentence-transformers` was never run; Beam Dataflow/Flink workers missing the package because the requirements file didn't include it.","commonSituations":"Fresh venv or CI container with only apache_beam installed; forgetting to ship extra dependencies to remote runners; a slim Docker image that trimmed ML dependencies.","solutions":["Install the dependency: pip install sentence-transformers.","Add sentence-transformers to your requirements file passed to the runner (--requirements_file for Dataflow).","Use a different embeddings manager (e.g. VertexAITextEmbeddings) if you cannot install the package."],"exampleFix":"// before\nembedder = HuggingfaceTextEmbeddings(model_name='sentence-transformers/all-MiniLM-L6-v2')\n\n// after\n# terminal: pip install sentence-transformers\nembedder = HuggingfaceTextEmbeddings(model_name='sentence-transformers/all-MiniLM-L6-v2')","handlingStrategy":"try-catch","validationCode":"import importlib.util\n\ndef sentence_transformers_available() -> bool:\n    return importlib.util.find_spec('sentence_transformers') is not None","typeGuard":null,"tryCatchPattern":"try:\n    embedder = HuggingfaceTextEmbeddings(model_name='sentence-transformers/all-MiniLM-L6-v2')\nexcept ImportError:\n    logging.error('Install: pip install sentence-transformers')\n    raise","preventionTips":["Pin sentence-transformers in the requirements file sent to your runner.","Verify worker environments with a startup import check or pip check in CI.","Prefer full ML base images over slim ones for embedding pipelines."],"tags":["python","apache-beam","importerror","huggingface","optional-dependency"],"backgroundTag":"missing-optional-dependency","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}