{"record":{"id":"8fcbcc793be4affa","repo":"deepset-ai/haystack","slug":"openaidocumentembedder-expects-a-list-of-documents-8fcbcc","errorCode":null,"errorMessage":"OpenAIDocumentEmbedder expects a list of Documents as input. In case you want to embed a string, please use the OpenAITextEmbedder.","messagePattern":"OpenAIDocumentEmbedder expects a list of Documents as input\\. In case you want to embed a string, please use the OpenAITextEmbedder\\.","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"haystack/components/embedders/openai_document_embedder.py","lineNumber":378,"sourceCode":"                new_documents.append(replace(doc))\n\n        return {\"documents\": new_documents, \"meta\": meta}\n\n    @component.output_types(documents=list[Document], meta=dict[str, Any])\n    async def run_async(self, documents: list[Document]) -> dict[str, Any]:\n        \"\"\"\n        Embeds a list of documents asynchronously.\n\n        :param documents:\n            A list of documents to embed.\n\n        :returns:\n            A dictionary with the following keys:\n            - `documents`: A list of documents with embeddings.\n            - `meta`: Information about the usage of the model.\n        \"\"\"\n        if not isinstance(documents, list) or documents and not isinstance(documents[0], Document):\n            raise TypeError(\n                \"OpenAIDocumentEmbedder expects a list of Documents as input. \"\n                \"In case you want to embed a string, please use the OpenAITextEmbedder.\"\n            )\n\n        await self.warm_up_async()\n\n        texts_to_embed = self._prepare_texts_to_embed(documents=documents)\n\n        doc_ids_to_embeddings, meta = await self._embed_batch_async(\n            texts_to_embed=texts_to_embed, batch_size=self.batch_size\n        )\n\n        new_documents = []\n        for doc in documents:\n            if doc.id in doc_ids_to_embeddings:\n                new_documents.append(replace(doc, embedding=doc_ids_to_embeddings[doc.id]))\n            else:\n                new_documents.append(replace(doc))","sourceCodeStart":360,"sourceCodeEnd":396,"githubUrl":"https://github.com/deepset-ai/haystack/blob/e318778c9bf60a1963e3b5f451359655dd696c30/haystack/components/embedders/openai_document_embedder.py#L360-L396","documentation":"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.","triggerScenarios":"Calling `embedder.run_async(documents=\"some text\")`, `documents=[\"a string\", \"another\"]`, or passing a single Document (not wrapped in a list) to run_async.","commonSituations":"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].","solutions":["Wrap input in a list of Document objects: `run_async(documents=[Document(content=text)])`","If the input is a plain string, switch to OpenAITextEmbedder","Check the upstream component's output type and connect it to the matching embedder"],"exampleFix":"// before\nawait embedder.run_async(documents=\"Paris is the capital of France\")\n// after\nfrom haystack import Document\nawait embedder.run_async(documents=[Document(content=\"Paris is the capital of France\")])","handlingStrategy":"type-guard","validationCode":"from haystack import Document\nif not isinstance(docs, list) or (docs and not isinstance(docs[0], Document)):\n    raise ValueError(\"OpenAIDocumentEmbedder requires list[Document]\")","typeGuard":"def is_document_list(value) -> bool:\n    return isinstance(value, list) and all(isinstance(d, Document) for d in value)","tryCatchPattern":"try:\n    result = await embedder.run_async(documents=docs)\nexcept TypeError as e:\n    if \"OpenAIDocumentEmbedder expects a list of Documents\" in str(e):\n        result = await text_embedder.run(text=str(docs))\n    else:\n        raise","preventionTips":["Connect only Document-producing components (converters, retrievers) into OpenAIDocumentEmbedder","Use OpenAITextEmbedder for raw strings","Wrap single strings with [Document(content=...)]","Add pipeline input type checks with `pipeline.connect()` which validates output/input types"],"tags":["python","type-error","embedders","openai"],"backgroundTag":"wrong-input-type-for-component","analyzedSha":"e318778c9bf60a1963e3b5f451359655dd696c30","analyzedAt":"2026-08-30T11:45:20.711Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}