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_async validates that its `documents` argument is a list whose first element is a haystack Document before embedding. It raises TypeError when the input is not a list or contains non-Document objects (e.g. raw strings), because this component computes per-document embeddings while the sibling OpenAITextEmbedder handles single strings.

Source

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

                new_documents.append(replace(doc))

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

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

        :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."
            )

        await self.warm_up_async()

        texts_to_embed = self._prepare_texts_to_embed(documents=documents)

        doc_ids_to_embeddings, meta = await self._embed_batch_async(
            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))

View on GitHub (pinned to e318778c9b)

Solutions

1. Wrap input in a list of Document objects: `run_async(documents=[Document(content=text)])`
2. If the input is a plain string, switch to OpenAITextEmbedder
3. Check the upstream component's output type and connect it to the matching embedder

Example fix

// before
await embedder.run_async(documents="Paris is the capital of France")
// after
from haystack import Document
await embedder.run_async(documents=[Document(content="Paris is the capital of France")])

from haystack import Document
if not isinstance(docs, list) or (docs and not isinstance(docs[0], Document)):
    raise ValueError("OpenAIDocumentEmbedder requires list[Document]")

def is_document_list(value) -> bool:
    return isinstance(value, list) and all(isinstance(d, Document) for d in value)

try:
    result = await embedder.run_async(documents=docs)
except TypeError as e:
    if "OpenAIDocumentEmbedder expects a list of Documents" in str(e):
        result = await text_embedder.run(text=str(docs))
    else:
        raise

When it happens

Trigger: Calling `embedder.run_async(documents="some text")`, `documents=["a string", "another"]`, or passing a single Document (not wrapped in a list) to run_async.

Common situations: Wiring a text string from an upstream converter directly into OpenAIDocumentEmbedder instead of OpenAITextEmbedder; passing a single Document object without wrapping it in a list; pipeline connections where a previous component outputs str instead of list[Document].

Related errors

• OpenAITextEmbedder expects a string as an input.In case you
• OpenAIDocumentEmbedder expects a list of Documents as input.
• Unsupported tool result: {result.result}
• Unsupported source type {type(source)}
• meta must be either None, a dictionary or a list of dictiona

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