{"record":{"id":"fa2a5c1dcb9453fb","repo":"deepset-ai/haystack","slug":"document-with-id-doc-id-is-missing-the-file","errorCode":null,"errorMessage":"Document with ID '{doc.id}' is missing the '{file_path_meta_field}' key in its metadata. Please ensure that the documents you are trying to convert have this key set.","messagePattern":"Document with ID '(.+?)' is missing the '(.+?)' key in its metadata\\. Please ensure that the documents you are trying to convert have this key set\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"haystack/components/converters/image/image_utils.py","lineNumber":245,"sourceCode":") -> list[_ImageSourceInfo]:\n    \"\"\"\n    Extracts the image source information from the documents.\n\n    :param documents: List of documents to extract image source information from.\n    :param file_path_meta_field: The metadata field in the Document that contains the file path to the image or PDF.\n    :param root_path: The root directory path where document files are located.\n\n    :returns:\n        A list of _ImageSourceInfo dictionaries, each containing the path and type of the image.\n        If the image is a PDF, the dictionary also contains the page number.\n    :raises ValueError: If the document is missing the file_path_meta_field key in its metadata, the file path is\n        invalid, the MIME type is not supported, or the page number is missing for a PDF document.\n    \"\"\"\n    images_source_info: list[_ImageSourceInfo] = []\n    for doc in documents:\n        file_path = doc.meta.get(file_path_meta_field)\n        if file_path is None:\n            raise ValueError(\n                f\"Document with ID '{doc.id}' is missing the '{file_path_meta_field}' key in its metadata.\"\n                f\" Please ensure that the documents you are trying to convert have this key set.\"\n            )\n\n        resolved_file_path = Path(root_path, file_path)\n\n        # When root_path is set, ensure the resolved path stays within it to block path-traversal\n        # payloads (e.g. \"../../etc/passwd\") coming from document metadata. When root_path is unset,\n        # file paths are treated as absolute by design and no containment check is applied; callers that\n        # process untrusted metadata should configure root_path (see component docstrings).\n        if root_path:\n            resolved_file_path = resolved_file_path.resolve()\n            resolved_root = Path(root_path).resolve()\n            if not resolved_file_path.is_relative_to(resolved_root):\n                raise ValueError(\n                    f\"Document with ID '{doc.id}' has a file path '{file_path}' that escapes the \"\n                    f\"configured root '{root_path}'. Resolved path: '{resolved_file_path}'.\"\n                )","sourceCodeStart":227,"sourceCodeEnd":263,"githubUrl":"https://github.com/deepset-ai/haystack/blob/e318778c9bf60a1963e3b5f451359655dd696c30/haystack/components/converters/image/image_utils.py#L227-L263","documentation":"When preparing image documents for conversion, image_utils reads each Document's file path from metadata (default 'file_path'). If that metadata key is absent, the component cannot locate the image on disk and raises ValueError naming the Document ID.","triggerScenarios":"Passing Documents to an image converter whose meta lacks the file_path_meta_field key — e.g. Documents built from text only, or meta key renamed ('path', 'source').","commonSituations":"Documents created by upstream converters that store the path under a different meta key; hand-built Documents in tests; upgrading haystack where the meta field name changed.","solutions":["Set doc.meta['file_path'] = '/path/to/image.png' before running the converter.","Pass the correct file_path_meta_field argument if your metadata uses a custom key.","Verify with print(doc.meta) which keys exist.","Re-run the upstream converter so paths are populated properly."],"exampleFix":"// before\ndocs = [Document(content=\"doc1\")]  # no meta\nconverter.run(documents=docs)\n// after\ndocs = [Document(content=\"doc1\", meta={\"file_path\": \"/data/img/doc1.png\"})]\nconverter.run(documents=docs)","handlingStrategy":"type-guard","validationCode":"def ensure_file_path_meta(docs, key=\"file_path\"):\n    missing = [d.id for d in docs if d.meta.get(key) is None]\n    if missing:\n        raise ValueError(f\"Documents missing '{key}' meta: {missing}\")","typeGuard":"def has_file_path(doc, key=\"file_path\") -> bool:\n    return isinstance(doc.meta.get(key), str) and len(doc.meta[key]) > 0","tryCatchPattern":"try:\n    result = converter.run(documents=docs)\nexcept ValueError as e:\n    if \"missing the\" in str(e) and \"key in its metadata\" in str(e):\n        doc_id = str(e).split(\"'\")[1]\n        docs = [d for d in docs if d.id != doc_id or d.meta.update({\"file_path\": resolve_path(d)})]\n        result = converter.run(documents=docs)\n    else:\n        raise","preventionTips":["Always set meta['file_path'] when creating image Documents.","Use the same meta key name throughout your pipeline; pass file_path_meta_field if customized.","Sanity-check upstream converters actually populate the key.","Add an assertion step in the pipeline before image conversion."],"tags":["python","metadata","missing-key","image"],"backgroundTag":"missing-metadata-key","analyzedSha":"e318778c9bf60a1963e3b5f451359655dd696c30","analyzedAt":"2026-08-30T11:45:20.711Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}