crewAIInc/crewAI · error · ImportError

Reading PDF URLs requires pymupdf. Install with: uv add pymu

Error message

Reading PDF URLs requires pymupdf. Install with: uv add pymupdf

What it means

UrlReadTool can fetch and parse PDF URLs, but PDF extraction lazily imports the optional 'pymupdf' package inside _extract_pdf. If pymupdf is not installed in the environment, reading a PDF URL raises ImportError with the install command.

Source

Thrown at lib/crewai-tools/src/crewai_tools/tools/url_read_tool/url_read_tool.py:248

    def _decode(self, body: bytes, content_type: str) -> str:
        """Decode *body* using the configured, declared, or default encoding.

        Falls back to a replacing UTF-8 decode rather than failing: partially
        readable text is more useful to an agent than an error.
        """
        encoding = self.encoding or _charset_from_content_type(content_type) or "utf-8"
        try:
            return body.decode(encoding)
        except (LookupError, UnicodeDecodeError):
            return body.decode("utf-8", errors="replace")

    @staticmethod
    def _extract_pdf(body: bytes) -> str:
        """Extract text from PDF bytes, page by page."""
        try:
            import pymupdf  # type: ignore[import-untyped]
        except ImportError as e:
            raise ImportError(
                "Reading PDF URLs requires pymupdf. Install with: uv add pymupdf"
            ) from e

        # Opened from memory: the bytes are already in hand, and a temp file
        # would need cleaning up on every error path.
        document = pymupdf.open(stream=body, filetype="pdf")
        try:
            pages = [
                f"Page {number}:\n{text}"
                for number, page in enumerate(document, 1)
                if (text := page.get_text().strip())
            ]
        finally:
            document.close()

        if not pages:
            return "[PDF with no extractable text]"
        return "\n\n".join(pages)

View on GitHub (pinned to 754d7323be)

Solutions

Install the dependency: uv add pymupdf (or pip install pymupdf).
Add pymupdf to your project dependencies if any workflow may read PDF URLs.
Catch ImportError around the read call and fall back to skipping/caching PDF URLs.

Example fix

# before
tool = UrlReadTool()
tool.run('https://example.com/report.pdf')  # ImportError: requires pymupdf

# after
# shell: uv add pymupdf
tool.run('https://example.com/report.pdf')

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util

if not importlib.util.find_spec('pymupdf'):
    # decide policy: skip PDFs or fail
    raise SystemExit('UrlReadTool needs pymupdf for PDF URLs: uv add pymupdf')

Try / catch

try:
    text = tool.run(url)
except ImportError as e:
    if 'pymupdf' in str(e):
        text = None  # or mark URL unsupported and continue
    else:
        raise

Prevention

Install pymupdf whenever your agent may fetch PDF links.
Pre-filter URLs by extension/content type against installed parsers.
Degrade gracefully: catch ImportError per-URL and report which parser is missing.

When it happens

Trigger: Calling UrlReadTool on a URL whose Content-Type is application/pdf (or a .pdf link) in an environment where pymupdf is not installed.

Common situations: Installing crewai-tools without the PDF extra; upgrading environments and dropping optional deps; only testing the tool against HTML pages so the PDF code path is never exercised until production.

Related errors

AI-assisted analysis of crewAIInc/crewAI@754d7323be (2026-08-15). Data as JSON: /api/errors/c42659f16ad254df. Report an issue: GitHub.