deepset-ai/haystack · error

Document with ID '{doc.id}' comes from the PDF file '{resolv

Error message

Document with ID '{doc.id}' comes from the PDF file '{resolved_file_path}' but is missing the 'page_number' key in its metadata. Please ensure that PDF documents you are trying to convert have this key set.

What it means

The ImageConverter (via _extract_image_sources_info) requires that any Document whose source is a PDF file carry a 'page_number' key in its metadata, since the converter must know which page of the PDF to render as an image. When a ByteStream/Document originating from a PDF lacks this key, the component raises ValueError because it cannot determine the page to convert.

Source

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

                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:
                raise ValueError(
                    f"Document with ID '{doc.id}' comes from the PDF file '{resolved_file_path}' but is missing "
                    f"the 'page_number' key in its metadata. Please ensure that PDF documents you are trying to "
                    f"convert have this key set."
                )
            image_info["page_number"] = page_number

        images_source_info.append(image_info)

    return images_source_info


class _PDFPageInfo(TypedDict):
    doc_idx: int
    path: Path
    page_number: int


def _batch_convert_pdf_pages_to_images(

View on GitHub (pinned to e318778c9b)

Solutions

1. Set doc.meta['page_number'] (1-based integer) on every PDF-sourced document before passing it to the converter
2. If the document comes from your own pipeline step, add the page number when creating the Document
3. If the document is not actually a PDF page, check why its mime type is 'application/pdf'; fix the upstream mime detection

Example fix

// before
doc = Document(content=text, meta={"source": "report.pdf"})
// after
doc = Document(content=text, meta={"source": "report.pdf", "page_number": 3})

def ensure_pdf_page_numbers(docs):
    for d in docs:
        if d.meta.get("mime_type") == "application/pdf" and d.meta.get("page_number") is None:
            raise ValueError(f"Document {d.id} missing 'page_number' in meta")
    return docs

def has_page_number(doc) -> bool:
    return isinstance(doc.meta.get("page_number"), int) and doc.meta["page_number"] > 0

try:
    result = converter.run(sources=streams)
except ValueError as e:
    if "page_number" in str(e):
        fix_or_skip_doc(e)
    else:
        raise

When it happens

Trigger: Calling ImageConverter.run() (or tests exercising _extract_image_sources_info) with a document whose mime type resolves to 'application/pdf' but whose doc.meta does not contain 'page_number'.

Common situations: Documents produced by a custom PDF splitter that forgets to record page_number; documents reconstructed from a database or cache where metadata was dropped; passing raw PDF-derived documents directly to the image converter instead of using PDFToImageConverter output.

Related errors

• No `jq_schema` nor `content_key` specified. Set either or bo
• The MSG file is encrypted and cannot be read.
• Invalid Jinja template '{template}': {e}
• No input data provided for output adaptation
• Undefined variable in the template {self.template}; kwargs:

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