crewAIInc/crewAI · error · FileValidationError

PDF '{filename}' page count ({page_count}) exceeds maximum (

Error message

PDF '{filename}' page count ({page_count}) exceeds maximum ({constraints.max_pages})

What it means

validate_pdf counts pages (when pypdf is available for probing) and raises FileValidationError when page_count > constraints.max_pages; the message shows both numbers. It runs after the size check, only when max_pages is set and the count could be determined.

Source

Thrown at lib/crewai-files/src/crewai_files/processing/validators.py:326

    errors: list[str] = []
    content = file.read()
    file_size = len(content)
    filename = file.filename

    _validate_size(
        "PDF", filename, file_size, constraints.max_size_bytes, errors, raise_on_error
    )

    if constraints.max_pages is not None:
        page_count = _get_pdf_page_count(content)
        if page_count is not None and page_count > constraints.max_pages:
            msg = (
                f"PDF '{filename}' page count ({page_count}) exceeds "
                f"maximum ({constraints.max_pages})"
            )
            errors.append(msg)
            if raise_on_error:
                raise FileValidationError(msg, file_name=filename)

    return errors


def validate_audio(
    file: AudioFile,
    constraints: AudioConstraints,
    *,
    raise_on_error: bool = True,
) -> Sequence[str]:
    """Validate an audio file against constraints.

    Args:
        file: The audio file to validate.
        constraints: Audio constraints to validate against.
        raise_on_error: If True, raise exceptions on validation failure.

    Returns:

View on GitHub (pinned to 754d7323be)

Solutions

Use FileHandling.CHUNK so the processor splits the PDF into max_pages-sized chunks (with overlap) instead of failing — requires pypdf.
Split the PDF upstream (PdfWriter page ranges) before ingestion.
Raise max_pages if the provider/model can actually handle more pages.
Catch FileValidationError and report the page counts to the user.

Example fix

# before
constraints = PDFConstraints(max_pages=50)
validate_pdf(big_pdf, constraints)  # FileValidationError: 120 pages exceeds maximum 50

# after
from crewai_files.processing.enums import FileHandling
processor = FileProcessor(constraints=constraints, handling=FileHandling.CHUNK)
chunks = processor.process(big_pdf)  # split into ~50-page chunks instead of raising

Defensive patterns

Strategy: validation

Validate before calling

from pypdf import PdfReader

page_count = len(PdfReader(io.BytesIO(content)).pages)
if constraints.max_pages is not None and page_count > constraints.max_pages:
    return chunk_or_split(file, page_count, constraints.max_pages)

Try / catch

from crewai_files.processing.exceptions import FileValidationError

try:
    processor.process(pdf_file)
except FileValidationError as e:
    if "page count" in str(e):
        # switch this file to CHUNK handling instead of STRICT
        return FileProcessor(constraints=constraints, handling=FileHandling.CHUNK).process(pdf_file)
    raise

Prevention

Use CHUNK mode for PDFs that may exceed max_pages (pypdf required).
Count pages (pypdf) before validation when page budget matters.
Split large documents upstream per chapter/section.

When it happens

Trigger: Validating a multi-page PDF (e.g. 120 pages) against PDFConstraints(max_pages=50) with raise_on_error=True, or processing it through FileProcessor in STRICT mode. Documents within the limit pass through untouched.

Common situations: Long manuals, contracts, or scanned reports exceeding provider context limits; constraints set to match a model's per-request page budget; concatenated PDFs created by a scanner feeding many documents into one file.

Related errors

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