{"record":{"id":"e40b35365a8783c4","repo":"agentscope-ai/agentscope","slug":"please-install-pypdf-to-use-the-pdf-parser-you-ca","errorCode":null,"errorMessage":"Please install pypdf to use the PDF parser. You can install it by `pip install pypdf` (or `pip install agentscope[rag]`).","messagePattern":"Please install pypdf to use the PDF parser\\. You can install it by `pip install pypdf` \\(or `pip install agentscope\\[rag\\]`\\)\\.","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"src/agentscope/rag/_parser/_pdf.py","lineNumber":69,"sourceCode":"            `list[Section]`:\n                One Section per page, in document order.  Each\n                section's metadata holds ``{\"page\": <starting at 1>}``.\n\n        Raises:\n            `FileNotFoundError`: If ``file`` is a ``str`` pointing to\n                a path that does not exist.\n            `ImportError`: If :mod:`pypdf` is not installed.\n            `ValueError`: If the bytes cannot be parsed as PDF.\n        \"\"\"\n        if isinstance(file, str):\n            with open(file, \"rb\") as fp:\n                file = fp.read()\n\n        try:\n            from pypdf import PdfReader\n            from pypdf.errors import PdfReadError\n        except ImportError as e:\n            raise ImportError(\n                \"Please install pypdf to use the PDF parser. \"\n                \"You can install it by `pip install pypdf` (or \"\n                \"`pip install agentscope[rag]`).\",\n            ) from e\n\n        try:\n            reader = PdfReader(io.BytesIO(file))\n        except PdfReadError as e:\n            raise ValueError(\n                f\"Failed to parse {filename!r} as PDF: {e}\",\n            ) from e\n\n        sections: list[Section] = []\n        for page_idx, page in enumerate(reader.pages, start=1):\n            text = page.extract_text() or \"\"\n            sections.append(\n                Section(\n                    content=TextBlock(text=text),","sourceCodeStart":51,"sourceCodeEnd":87,"githubUrl":"https://github.com/agentscope-ai/agentscope/blob/e90f1c7592896cc95f6e5ee506194f533378247d/src/agentscope/rag/_parser/_pdf.py#L51-L87","documentation":"The PDF parser needs the optional pypdf dependency. Its import inside parse() failed, raising ImportError with install instructions chained to the original error.","triggerScenarios":"Calling PDFParser.parse(...) without pypdf installed (agentscope installed without [rag] extra).","commonSituations":"Base agentscope install in slim containers; forgetting optional extras in deployment images.","solutions":["pip install pypdf (or pip install 'agentscope[rag]')","Pin pypdf in your project dependencies","Feature-detect at startup if PDF ingestion is optional"],"exampleFix":"# before\nPDFParser().parse('doc.pdf')  # ImportError\n\n# after\n# pip install 'agentscope[rag]'\nPDFParser().parse('doc.pdf')","handlingStrategy":"validation","validationCode":"try:\n    import pypdf  # noqa\n    pdf_ok = True\nexcept ImportError:\n    pdf_ok = False","typeGuard":null,"tryCatchPattern":"try:\n    parser.parse(f)\nexcept ImportError as e:\n    if 'pypdf' not in str(e):\n        raise\n    logger.warning('PDF parsing disabled: install pypdf')","preventionTips":["Include agentscope[rag] in deployment images","Check optional deps before enabling document ingestion features"],"tags":["agentscope","rag","pdf","missing-dependency","pypdf"],"backgroundTag":"missing-optional-dependency","analyzedSha":"e90f1c7592896cc95f6e5ee506194f533378247d","analyzedAt":"2026-08-28T18:24:12.087Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}