Document with ID '{doc.id}' is missing the '{file_path_meta_

Error message

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.

What it means

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.

Source

Thrown at haystack/components/converters/image/image_utils.py:245

) -> list[_ImageSourceInfo]:
    """
    Extracts the image source information from the documents.

    :param documents: List of documents to extract image source information from.
    :param file_path_meta_field: The metadata field in the Document that contains the file path to the image or PDF.
    :param root_path: The root directory path where document files are located.

    :returns:
        A list of _ImageSourceInfo dictionaries, each containing the path and type of the image.
        If the image is a PDF, the dictionary also contains the page number.
    :raises ValueError: If the document is missing the file_path_meta_field key in its metadata, the file path is
        invalid, the MIME type is not supported, or the page number is missing for a PDF document.
    """
    images_source_info: list[_ImageSourceInfo] = []
    for doc in documents:
        file_path = doc.meta.get(file_path_meta_field)
        if file_path is None:
            raise ValueError(
                f"Document with ID '{doc.id}' is missing the '{file_path_meta_field}' key in its metadata."
                f" Please ensure that the documents you are trying to convert have this key set."
            )

        resolved_file_path = Path(root_path, file_path)

        # When root_path is set, ensure the resolved path stays within it to block path-traversal
        # payloads (e.g. "../../etc/passwd") coming from document metadata. When root_path is unset,
        # file paths are treated as absolute by design and no containment check is applied; callers that
        # process untrusted metadata should configure root_path (see component docstrings).
        if root_path:
            resolved_file_path = resolved_file_path.resolve()
            resolved_root = Path(root_path).resolve()
            if not resolved_file_path.is_relative_to(resolved_root):
                raise ValueError(
                    f"Document with ID '{doc.id}' has a file path '{file_path}' that escapes the "
                    f"configured root '{root_path}'. Resolved path: '{resolved_file_path}'."
                )

View on GitHub (pinned to e318778c9b)

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.

Example fix

// before
docs = [Document(content="doc1")]  # no meta
converter.run(documents=docs)
// after
docs = [Document(content="doc1", meta={"file_path": "/data/img/doc1.png"})]
converter.run(documents=docs)

Defensive patterns

Strategy: type-guard

Validate before calling

def ensure_file_path_meta(docs, key="file_path"):
    missing = [d.id for d in docs if d.meta.get(key) is None]
    if missing:
        raise ValueError(f"Documents missing '{key}' meta: {missing}")

Type guard

def has_file_path(doc, key="file_path") -> bool:
    return isinstance(doc.meta.get(key), str) and len(doc.meta[key]) > 0

Try / catch

try:
    result = converter.run(documents=docs)
except ValueError as e:
    if "missing the" in str(e) and "key in its metadata" in str(e):
        doc_id = str(e).split("'")[1]
        docs = [d for d in docs if d.id != doc_id or d.meta.update({"file_path": resolve_path(d)})]
        result = converter.run(documents=docs)
    else:
        raise

Prevention

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.

When it happens

Trigger: 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').

Common situations: 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.

Related errors

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