{"record":{"id":"8f6ae77597e012f3","repo":"deepset-ai/haystack","slug":"openaidocumentembedder-expects-a-list-of-documents","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":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"haystack/components/embedders/openai_document_embedder.py","lineNumber":344,"sourceCode":"                meta[\"usage\"][\"total_tokens\"] += response.usage.total_tokens\n\n        return doc_ids_to_embeddings, meta\n\n    @component.output_types(documents=list[Document], meta=dict[str, Any])\n    def run(self, documents: list[Document]) -> dict[str, Any]:\n        \"\"\"\n        Embeds a list of documents.\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        self.warm_up()\n\n        texts_to_embed = self._prepare_texts_to_embed(documents=documents)\n\n        doc_ids_to_embeddings, meta = self._embed_batch(texts_to_embed=texts_to_embed, batch_size=self.batch_size)\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))\n\n        return {\"documents\": new_documents, \"meta\": meta}","sourceCodeStart":326,"sourceCodeEnd":362,"githubUrl":"https://github.com/deepset-ai/haystack/blob/e318778c9bf60a1963e3b5f451359655dd696c30/haystack/components/embedders/openai_document_embedder.py#L326-L362","documentation":"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.","triggerScenarios":"`OpenAIDocumentEmbedder().run(\"text\")`, `.run([\"a\", \"b\"])`, `.run([{\"content\": \"x\"}])` — anything that is not a list whose first element is a Document instance.","commonSituations":"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.","solutions":["Wrap inputs: `run([Document(content=t) for t in texts])`","Use OpenAITextEmbedder if you truly want to embed a single string","Inspect the component feeding this one in your pipeline and fix its output type"],"exampleFix":"// before\nresult = embedder.run(\"hello world\")\n// after\nfrom haystack.dataclasses import Document\nresult = embedder.run([Document(content=\"hello world\")])","handlingStrategy":"type-guard","validationCode":"from haystack.dataclasses import Document\nassert isinstance(documents, list) and (not documents or isinstance(documents[0], Document))\nresult = embedder.run(documents)","typeGuard":"def is_document_list(value) -> bool:\n    from haystack.dataclasses import Document\n    return isinstance(value, list) and (len(value) == 0 or isinstance(value[0], Document))","tryCatchPattern":"try:\n    result = embedder.run(documents)\nexcept TypeError as e:\n    if isinstance(documents, str):\n        result = OpenAITextEmbedder().run(documents)\n    else:\n        raise","preventionTips":["Always construct Document objects, never pass raw strings/dicts to OpenAIDocumentEmbedder","Choose OpenAITextEmbedder for single-string embedding needs","Verify pipeline wiring: output type of upstream component must be list[Document]"],"tags":["type-error","openai","documents","python"],"backgroundTag":"wrong-input-type","analyzedSha":"e318778c9bf60a1963e3b5f451359655dd696c30","analyzedAt":"2026-08-30T11:45:20.711Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}