deepset-ai/haystack · error · TypeError

OpenAIDocumentEmbedder expects a list of Documents as input.

Error message

OpenAIDocumentEmbedder expects a list of Documents as input.In case you want to embed a string, please use the OpenAITextEmbedder.

What it means

OpenAIDocumentEmbedder.run expects a list of haystack Document objects as its `documents` argument. If `documents` is not a list or its first element is not a Document, it raises this TypeError and points to OpenAITextEmbedder for plain strings. The error is raised before any API call, so nothing is sent to OpenAI.

Source

Thrown at haystack/components/embedders/openai_document_embedder.py:344

                meta["usage"]["total_tokens"] += response.usage.total_tokens

        return doc_ids_to_embeddings, meta

    @component.output_types(documents=list[Document], meta=dict[str, Any])
    def run(self, documents: list[Document]) -> dict[str, Any]:
        """
        Embeds a list of documents.

        :param documents:
            A list of documents to embed.

        :returns:
            A dictionary with the following keys:
            - `documents`: A list of documents with embeddings.
            - `meta`: Information about the usage of the model.
        """
        if not isinstance(documents, list) or documents and not isinstance(documents[0], Document):
            raise TypeError(
                "OpenAIDocumentEmbedder expects a list of Documents as input."
                "In case you want to embed a string, please use the OpenAITextEmbedder."
            )

        self.warm_up()

        texts_to_embed = self._prepare_texts_to_embed(documents=documents)

        doc_ids_to_embeddings, meta = self._embed_batch(texts_to_embed=texts_to_embed, batch_size=self.batch_size)

        new_documents = []
        for doc in documents:
            if doc.id in doc_ids_to_embeddings:
                new_documents.append(replace(doc, embedding=doc_ids_to_embeddings[doc.id]))
            else:
                new_documents.append(replace(doc))

        return {"documents": new_documents, "meta": meta}

View on GitHub (pinned to e318778c9b)

Solutions

1. Wrap inputs: `run([Document(content=t) for t in texts])`
2. Use OpenAITextEmbedder if you truly want to embed a single string
3. Inspect the component feeding this one in your pipeline and fix its output type

Example fix

// before
result = embedder.run("hello world")
// after
from haystack.dataclasses import Document
result = embedder.run([Document(content="hello world")])

from haystack.dataclasses import Document
assert isinstance(documents, list) and (not documents or isinstance(documents[0], Document))
result = embedder.run(documents)

def is_document_list(value) -> bool:
    from haystack.dataclasses import Document
    return isinstance(value, list) and (len(value) == 0 or isinstance(value[0], Document))

try:
    result = embedder.run(documents)
except TypeError as e:
    if isinstance(documents, str):
        result = OpenAITextEmbedder().run(documents)
    else:
        raise

When it happens

Trigger: `OpenAIDocumentEmbedder().run("text")`, `.run(["a", "b"])`, `.run([{"content": "x"}])` — anything that is not a list whose first element is a Document instance.

Common situations: Wiring a TextEmbedder into a slot expecting a DocumentEmbedder in a pipeline; forgetting `Document(content=...)` wrapping; sending a pandas/JSON list of dicts straight to run; empty-string handling confusion.

Related errors

• MockDocumentEmbedder expects a list of Documents as input.In
• OpenAIDocumentEmbedder expects a list of Documents as input.
• OpenAITextEmbedder expects a string as an input.In case you
• Unsupported tool result: {result.result}
• Unsupported source type {type(source)}

AI-assisted analysis of deepset-ai/haystack@e318778c9b (2026-08-30). Data as JSON: /api/errors/8f6ae77597e012f3. Report an issue: GitHub.