{"record":{"id":"733af7614f89c91b","repo":"deepset-ai/haystack","slug":"document-with-id-doc-id-comes-from-the-pdf-fil","errorCode":null,"errorMessage":"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.","messagePattern":"Document with ID '(.+?)' comes from the PDF file '(.+?)' but is missing the 'page_number' key in its metadata\\. Please ensure that PDF 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":285,"sourceCode":"                f\"Document with ID '{doc.id}' has an invalid file path '{resolved_file_path}'. \"\n                f\"Please ensure that the documents you are trying to convert have valid file paths.\"\n            )\n\n        mime_type = doc.meta.get(\"mime_type\") or mimetypes.guess_type(resolved_file_path)[0]\n        if mime_type not in IMAGE_MIME_TYPES:\n            raise ValueError(\n                f\"Document with file path '{resolved_file_path}' has an unsupported MIME type '{mime_type}'. \"\n                f\"Please ensure that the documents you are trying to convert are of the supported \"\n                f\"types: {', '.join(IMAGE_MIME_TYPES)}.\"\n            )\n\n        image_info: _ImageSourceInfo = {\"path\": resolved_file_path, \"mime_type\": mime_type}\n\n        # If mimetype is PDF we also need the page number to be able to convert the right page\n        if mime_type == \"application/pdf\":\n            page_number = doc.meta.get(\"page_number\")\n            if page_number is None:\n                raise ValueError(\n                    f\"Document with ID '{doc.id}' comes from the PDF file '{resolved_file_path}' but is missing \"\n                    f\"the 'page_number' key in its metadata. Please ensure that PDF documents you are trying to \"\n                    f\"convert have this key set.\"\n                )\n            image_info[\"page_number\"] = page_number\n\n        images_source_info.append(image_info)\n\n    return images_source_info\n\n\nclass _PDFPageInfo(TypedDict):\n    doc_idx: int\n    path: Path\n    page_number: int\n\n\ndef _batch_convert_pdf_pages_to_images(","sourceCodeStart":267,"sourceCodeEnd":303,"githubUrl":"https://github.com/deepset-ai/haystack/blob/e318778c9bf60a1963e3b5f451359655dd696c30/haystack/components/converters/image/image_utils.py#L267-L303","documentation":"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.","triggerScenarios":"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'.","commonSituations":"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.","solutions":["Set doc.meta['page_number'] (1-based integer) on every PDF-sourced document before passing it to the converter","If the document comes from your own pipeline step, add the page number when creating the Document","If the document is not actually a PDF page, check why its mime type is 'application/pdf'; fix the upstream mime detection"],"exampleFix":"// before\ndoc = Document(content=text, meta={\"source\": \"report.pdf\"})\n// after\ndoc = Document(content=text, meta={\"source\": \"report.pdf\", \"page_number\": 3})","handlingStrategy":"validation","validationCode":"def ensure_pdf_page_numbers(docs):\n    for d in docs:\n        if d.meta.get(\"mime_type\") == \"application/pdf\" and d.meta.get(\"page_number\") is None:\n            raise ValueError(f\"Document {d.id} missing 'page_number' in meta\")\n    return docs","typeGuard":"def has_page_number(doc) -> bool:\n    return isinstance(doc.meta.get(\"page_number\"), int) and doc.meta[\"page_number\"] > 0","tryCatchPattern":"try:\n    result = converter.run(sources=streams)\nexcept ValueError as e:\n    if \"page_number\" in str(e):\n        fix_or_skip_doc(e)\n    else:\n        raise","preventionTips":["Always set page_number in meta when creating documents from PDF pages","Reuse PDFToImageConverter/splitters that populate page_number automatically","Assert metadata completeness in a pipeline pre-step"],"tags":["python","haystack","image-converter","pdf","missing-metadata"],"backgroundTag":"missing-metadata-key","analyzedSha":"e318778c9bf60a1963e3b5f451359655dd696c30","analyzedAt":"2026-08-30T11:45:20.711Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}