ImportError: Cannot import 'convert' from 'haystack.utils.filters'

[sethantanah]

Describe the bug

When attempting to import the convert function from haystack.utils.filters, the system raises an ImportError. This breaks pipeline initialization for tasks requiring this utility function.

---

Error message

ImportError: cannot import name 'convert' from 'haystack.utils.filters'  
(/root/app/.venv/lib/python3.10/site-packages/haystack/utils/filters.py)

---

Expected behavior

The convert function should be importable from haystack.utils.filters as part of the public API, consistent with Haystack’s documentation.

---

Additional context

• Document types: Attempting to process PDF/HTML documents with custom preprocessing.
• Preprocessing: Using Haystack’s PreProcessor with custom clean_ functions.
• Pipeline: Fails during retriever initialization in a ExtractiveQAPipeline.
• Temporary workaround: Manually commenting out the import in filters.py resolves the issue.

---

To Reproduce

1. Install haystack-ai version 2.1.1 (from pip/source).
2. Create a pipeline with any component requiring haystack.utils.filters.
3. Attempt to import:

   from haystack.utils.filters import convert
   

4. Observe ImportError.

---

FAQ Check

• [x] Confirmed this is not addressed in Haystack FAQ.

---

System

• OS: Ubuntu 22.04 (Dockerized)
• GPU/CPU: NVIDIA CUDA 12.0 (A100)
• Haystack version: 1.15.0 (from PyPI)
• DocumentStore: ElasticsearchDocumentStore
• Reader: FARMReader (model: deepset/roberta-base-squad2)
• Retriever: EmbeddingRetriever (using sentence-transformers/all-MiniLM-L6-v2)

---

Suggested Labels

bug, utils, import-issue

---

Notes for Developers

1. Likely caused by a missing export in filters.py or version mismatch.
2. Critical for users relying on programmatic pipeline configuration.

[sethantanah]

haystack-ai = {extras = ["all"], version = "^2.1.1"} opensearch-haystack = "^0.3.0"

from .document_store import OpenSearchDocumentStore File "/root/app/.venv/lib/python3.10/site-packages/haystack_integrations/document_stores/opensearch/document_store.py", line 12, in from haystack.utils.filters import convert ImportError: cannot import name 'convert' from 'haystack.utils.filters' (/root/app/.venv/lib/python3.10/site-packages/haystack/utils/filters.py)

[sjrl]

Hey @sethantanah sorry to hear that you've run into trouble during an haystack-ai upgrade. We have a deprecation policy that we follow (see here) for how we provide notice to users if we make any breaking changes to Haystack.

In this case we deprecated the old filter syntax used in Haystack v1 in Haystack version 2.6.0. You can see in our release notes here for v2.6.0 that we have a note in the Upgrade Notes section saying that we will only support the v2 filter syntax.

The initial deprecation notice was announced in Haystack v2.4.0 which you can see here in our release notes under the Deprecation Notes header.

So we'd recommend following the docs here for how to upgrade to using the v2 filter syntax.