Document with ID '{doc.id}' has an invalid file path '{resol

Error message

Document with ID '{doc.id}' has an invalid file path '{resolved_file_path}'. Please ensure that the documents you are trying to convert have valid file paths.

What it means

After containment checks, the component verifies the resolved path actually exists and is a regular file via Path.is_file(). Missing files, directories, or broken symlinks raise this ValueError naming the resolved path and Document ID.

Source

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

            )

        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}'."
                )

        if not resolved_file_path.is_file():
            raise ValueError(
                f"Document with ID '{doc.id}' has an invalid file path '{resolved_file_path}'. "
                f"Please ensure that the documents you are trying to convert have valid file paths."
            )

        mime_type = doc.meta.get("mime_type") or mimetypes.guess_type(resolved_file_path)[0]
        if mime_type not in IMAGE_MIME_TYPES:
            raise ValueError(
                f"Document with file path '{resolved_file_path}' has an unsupported MIME type '{mime_type}'. "
                f"Please ensure that the documents you are trying to convert are of the supported "
                f"types: {', '.join(IMAGE_MIME_TYPES)}."
            )

        image_info: _ImageSourceInfo = {"path": resolved_file_path, "mime_type": mime_type}

        # If mimetype is PDF we also need the page number to be able to convert the right page
        if mime_type == "application/pdf":
            page_number = doc.meta.get("page_number")
            if page_number is None:

View on GitHub (pinned to e318778c9b)

Solutions

Verify the file exists: Path(root_path, file_path).is_file() before running.
Fix the file_path value in document metadata or re-index with correct paths.
Copy/mount the missing files into the expected location.
Check filename case and extensions match exactly on disk.

Example fix

// before
doc.meta["file_path"] = "/data/old_run/img.png"  # file deleted
converter.run(documents=docs)
// after
assert Path(doc.meta["file_path"]).is_file()
doc.meta["file_path"] = "/data/new_run/img.png"
converter.run(documents=docs)

Defensive patterns

Strategy: validation

Validate before calling

from pathlib import Path
def filter_existing(docs, root_path=None, key="file_path"):
    ok = []
    for d in docs:
        p = Path(root_path, d.meta.get(key, "")) if root_path else Path(d.meta.get(key, ""))
        if p.is_file():
            ok.append(d)
        else:
            logger.warning("Skipping %s: %s does not exist", d.id, p)
    return ok

Type guard

def file_exists(doc, root=None, key="file_path") -> bool:
    fp = doc.meta.get(key)
    if not isinstance(fp, str):
        return False
    return (Path(root, fp) if root else Path(fp)).is_file()

Try / catch

try:
    result = converter.run(documents=docs)
except ValueError as e:
    if "invalid file path" in str(e):
        bad = str(e).split("'")[1]
        docs = [d for d in docs if str(Path(d.meta["file_path"])) != bad]
        result = converter.run(documents=docs) if docs else {"images": []}
    else:
        raise

Prevention

Check Path(file_path).is_file() for each document before running.
Re-index after moving/migrating data files.
Mount the same data volume your indexer used.
Watch Linux case-sensitivity; verify exact filenames.

When it happens

Trigger: Document meta file_path points to a non-existent file, a directory, or a broken symlink; files deleted/moved after indexing; wrong root_path making resolved path not exist.

Common situations: Index built on another machine/container where files aren't mounted; temp files cleaned up; paths stored before a data migration; case-sensitivity mismatch on Linux (Image.PNG vs image.png).

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

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